@adukiorg/anza 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -2,7 +2,7 @@
 
 All notable changes to `@adukiorg/anza` will be documented here.
 
-Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).  
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
@@ -16,11 +16,85 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.2.2] — 2026-06-09
+
+### Added
+
+- CI/CD workflows for GitHub Actions (build, typecheck, verify scaffolding, cross-platform release)
+- Comprehensive documentation for all modules (animations, api, events, platform, router, security, state, storage, sw, ui, workers)
+- `library/bin/` CLI wrappers for Node.js distribution
+
+---
+
+## [0.2.1] — 2026-06-09
+
+### Added
+
+#### Service Worker Toolkit — `@adukiorg/anza/sw`
+
+- **New subpath export** `@adukiorg/anza/sw` — caching strategies, route interception, background sync, and push notifications
+- **Seven caching strategies**: CacheFirst, NetworkFirst, StaleRevalidate, CacheThenNetwork, NetworkOnly, CacheOnly, OfflineFallback
+- **URLPattern routing** inside the Service Worker via `router()` and `Router`
+- **Install/activate helpers**: `precache()`, `pruneStale()`, `claim()`, `enableNavPreload()`
+- **TTL expiry**: `pruneExpired()`, `setupAutoPrune()` with `x-expires-at` headers
+- **Background sync**: `replayQueue()`, `requeueFailed()` with dead-letter queue
+- **Request serialization**: `serializeRequest()`, `deserializeRequest()` for IndexedDB storage
+- **Push notifications**: `subscribe()`, `notify()` with VAPID support
+- **Scaffolded `src/sw.js`** generated by both `anza create` and `anza-create`
+
+#### Theme Switching — `@adukiorg/anza/theme`
+
+- **New subpath export** `@adukiorg/anza/theme`
+- **Auto-init on import** — reads saved preference from `localStorage` or respects `prefers-color-scheme`
+- **Attaches to `window.theme`** via `Object.defineProperty` (non-enumerable, non-configurable)
+- **API**: `theme.get()`, `theme.set()`, `theme.toggle()` — all update the same global instance
+- **No manual init required** — importing `@adukiorg/anza/ui` triggers it automatically
+
+#### View Transition Tokens — `tokens/semantic/transitions.css`
+
+- **New semantic token layer** connecting the CSS View Transitions API to the design token system
+- **Tokens**: `--transition-bg`, `--transition-duration`, `--transition-easing`, `--transition-push`, `--transition-pop`, `--transition-replace`
+- **Router `transitions.run()`** injects a token-aware stylesheet on first use
+- **Dock `swap()`** reads directional easing from tokens (`--transition-push` vs `--transition-pop`) for physically different forward/back feel
+- **High-contrast theme morphing** — `contrast.css` now declares `transition:` for smooth token interpolation
+
+#### Documentation
+
+- **Comprehensive `docs/index.md`** — master docs entry with all modules listed by usefulness
+- **`docs/sw/`** — complete SW documentation: `index.md`, `start.md`, `strategies.md`, `routes.md`, `sync.md`, `api.md`
+- **Updated `docs/intro/`** — SW toolkit in feature list, build output includes `dist/sw.js`
+- **View Transition token docs** added to `docs/ui/transitions.md`, `docs/router/transitions.md`, `docs/animations/tokens.md`
+
+#### Tooling
+
+- **`tools/src/build/graph.rs` split** into focused modules:
+  - `cache.rs` — incremental build cache (`.anzacache.json`)
+  - `parse.rs` — ESM AST parsing with swc
+  - `entries.rs` — entry point discovery from HTML and `src/sw.js`
+  - `resolve.rs` — import map and filesystem resolution
+  - `html.rs` — HTML injection (importmap link, HMR script)
+  - `sw.rs` — Service Worker bare-specifier rewriting
+- **Auto-discovery of `src/sw.js`** as a build entry point
+- **Bare specifier rewriting in `dist/sw.js`** — `@adukiorg/anza/sw` → `./sw/index.js` (SW does not support import maps)
+
+### Changed
+
+- **Cache file renamed** from `.anza-build-cache.json` to `.anzacache.json`
+- **Scaffolded `src/app.js`** now imports and auto-registers the Service Worker
+- **Scaffolded `src/sw.js`** included in both Node.js and Rust `create` commands
+
+### Fixed
+
+- High-contrast theme (`contrast.css`) now animates token changes instead of snapping instantly
+
+---
+
 ## [0.2.0] — 2026-06-07
 
 ### Added
 
 #### Compiler — `anza`
+
 - **Dependency Graph Walking**: Automated dependency resolution of ESM imports/exports.
 - **Tree-Shaking**: Outputs only referenced files to `dist/`, excluding unused code.
 - **Automatic Inline Importmaps**: Optimal `<script type="importmap">` generated and injected inline into HTML entry points.
@@ -30,9 +104,11 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 - **Nested /dist Routing**: Added router nested service mapping in Axum dev server for development path parity.
 
 #### Structure
+
 - **Monorepo Split**: Reorganized files into `/library` (NPM package), `/sample` (demo application), and `/tools` (Rust compiler).
 
 #### Sample
+
 - **Cyberpunk Blog SPA**: Features reactive store, category filters, instant search, likes count persistence, details page with lightweight custom markdown renderer, post publishing, and post deletion.
 
 ---
@@ -132,6 +208,7 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 - `blog/` — sample SPA demonstrating state, storage, offline queue, and animations
 - Import map mirrors the published `@adukiorg/anza/*` subpath exports exactly
 
-[Unreleased]: https://github.com/aduki-org/native/compare/v0.2.0...HEAD
-[0.2.0]: https://github.com/aduki-org/native/compare/v0.1.0...v0.2.0
-[0.1.0]: https://github.com/aduki-org/native/releases/tag/v0.1.0
+[Unreleased]: https://github.com/aduki-org/anza/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/aduki-org/anza/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/aduki-org/anza/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/aduki-org/anza/releases/tag/v0.1.0

package/README.md

@@ -1,6 +1,6 @@
 # @adukiorg/anza
 
-> Anza web platform library. Pure browser ESM — no bundler, no framework lock-in. A small local Rust toolchain resolves your import graph into a minimal, browser-native `dist/`.
+> The browser already knows how to render, route, cache, and animate. We just stopped getting in its way.
 
 [![npm](https://img.shields.io/npm/v/@adukiorg/anza)](https://www.npmjs.com/package/@adukiorg/anza)
 [![license](https://img.shields.io/npm/l/@adukiorg/anza)](./LICENSE)
@@ -8,206 +8,170 @@
 
 ---
 
-## What is this?
+## What This Is (and What It Is Not)
 
-`@adukiorg/anza` is a modular, zero-dependency platform library built entirely on top of browser-native APIs:
+**This is** a web platform library that treats the browser as the runtime. It gives you reactive state, client-side routing, custom elements, offline sync, and animations — all as plain ES modules the browser resolves directly. No bundler. No virtual DOM. No framework lock-in.
 
-| Module | What it wraps |
-| --- | --- |
-| `/api` | `fetch`, Streams API, `scheduler.postTask` |
-| `/state` | ES Proxy, `queueMicrotask`, `BroadcastChannel` |
-| `/events` | Custom pub/sub with AbortSignal cleanup |
-| `/router` | Navigation API, History API |
-| `/storage` | IndexedDB, Cache API, OPFS, LRU memory |
-| `/offline` | IDB-backed operation queue, `navigator.onLine` |
-| `/animations` | WAAPI (`element.animate`), stagger groups |
-| `/workers` | Web Locks API, Web Workers pool |
-| `/security` | Web Crypto API, `DOMParser` XSS sanitizer |
-| `/platform` | Feature detection for 30+ browser APIs |
-| `/ui` | Shadow DOM base element, design token cascade |
-| `/elements` | Custom element library |
+**This is NOT** another React competitor. If you love JSX, useEffect cleanup races, and wondering why your bundle is 400KB, Anza is not for you. We are not trying to replace React. React is fine. React is great. React is for people who enjoy debugging `useMemo` dependency arrays at 2am. We are for people who want to write `.js` files and let the browser do what it was built to do.
 
-No virtual DOM. No transpilation. The library is authored as plain `.js` files in `library/src/`. The bundled-in Rust toolchain (`tools/`) walks your ESM `import` graph from your entry points and emits **only the modules you actually use** into `dist/`, preserving a folder structure the browser resolves natively.
+**This is NOT** Angular. We do not have a CLI that generates fourteen files to render a button. We have `element('my-button', { template: '<button>Click me</button>' })`. That is the whole API.
 
----
-
-## Installation
-
-To install `@adukiorg/anza` in your project:
-
-```bash
-npm install @adukiorg/anza
-```
+**This is NOT** Vue. We do not have a template compiler. We do not have a virtual DOM diffing algorithm that runs in JavaScript to figure out what the browser should have already figured out. We write HTML. The browser parses HTML. It has been doing this since 1993. It is pretty good at it.
 
 ---
 
-## Workspace Structure
+## The Pitch
 
-The codebase is organized as a monorepo containing:
+Anza is built on browser-native APIs. Every module wraps something the browser already ships:
 
-- **`library/`**: The core package codebase (`src/`, `tests/`, `package.json`, etc.).
-- **`sample/`**: A sample application demonstrating reactive state, routing, and component separation in action.
-- **`tools/`**: The Rust compiler toolchain codebase (`anza`).
-- **`scripts/`**: Toolchain build and release helper scripts.
+| Module | What it wraps | What we did to it |
+| --- | --- | --- |
+| `/api` | `fetch`, Streams API, `scheduler.postTask` | Added retries, caching, and a pipeline. The browser did the hard part. |
+| `/state` | ES Proxy, `queueMicrotask`, `BroadcastChannel` | Reactive stores with batched updates. No getters/setters boilerplate. |
+| `/events` | `CustomEvent`, `AbortSignal` | Pub/sub with cleanup that actually works. |
+| `/router` | Navigation API, History API, `URLPattern` | Routes that match URLs and render views. Shocking, we know. |
+| `/storage` | IndexedDB, Cache API, OPFS | Tiered persistence: memory → IDB → disk. You pick the tier. |
+| `/offline` | `navigator.onLine`, IndexedDB | Queue failed requests, replay them later. Like a polite retry system. |
+| `/animations` | WAAPI (`element.animate`) | Stagger groups and scroll-driven animations. The GPU does the work. |
+| `/workers` | Web Locks API, Web Workers | A worker pool with concurrency limits. Because tabs deserve boundaries. |
+| `/security` | Web Crypto API, `DOMParser` | Encrypt, hash, sanitize. The browser has a crypto lab. We use it. |
+| `/platform` | 30+ browser APIs | Feature detection so you know what you are working with. |
+| `/ui` | Custom Elements, Shadow DOM, CSS Layers | Declarative components with reactive props and lifecycle hooks. No classes. |
+| `/sw` | Service Worker, Cache API, Background Sync | Caching strategies, route interception, and push notifications. |
+| `/theme` | `data-theme`, `localStorage`, `matchMedia` | Auto theme switching with persistence. Light, dark, or high-contrast. |
 
----
+The Rust CLI (`anza`) resolves your ESM import graph and copies only the modules you actually use into `dist/`. It generates type declarations, serves with HMR, and gets out of your way.
 
-## Building the Toolchain & Running the Sample
+---
 
-The compiler (`anza`) is a native Rust CLI that manages the build pipeline.
+## Quick Start
 
-### 1. Build the compiler
-From the workspace root directory:
 ```bash
-node scripts/build.js
+npx anza-create myapp
+cd myapp
+npm install
+npm run dev
 ```
-This builds the release binary into `tools/target/release/anza`.
 
-### 2. Run the Sample Application
-Navigate into the sample project:
-```bash
-cd sample
-npm install     # Links to the local library package
-npm run build   # Performs graph resolution and emits output to dist/
-npm run dev     # Starts dev server on port 8080 with HMR and routing fallbacks
-```
+That is it. Your browser loads `dist/app.js` natively. No webpack. No vite. No `npm run build` that takes forty seconds.
 
 ---
 
-## What the Toolchain Does
+## What You Actually Write
 
-- **Graph Walking**: Resolves the full import graph starting from your entry points (`src/index.js` by default, plus module scripts found in HTML templates).
-- **Tree-Shaking**: Copies only the reached modules into `dist/`. Unreferenced files and assets are completely excluded.
-- **Automatic Inline Importmap**: Analyzes import references and automatically generates/injects an optimal `<script type="importmap">` tag inline in your HTML files.
-- **Static Asset Copying**: Automatically copies templates (`.html`) and stylesheets (`.css`) referenced by your components.
-- **Strict Validation**: Fails the build on unresolved imports, syntax errors, or invalid component prop declarations.
-- **HMR Dev Server**: Serves your files with a SSE live-reload listener. Modifying a CSS file hot-swaps it in place; HTML/JS modifications trigger a fast page reload.
+### A Component
 
----
+```javascript
+import { view } from '@adukiorg/anza/defs';
 
-## Splitting a Component Across Files
+view('user-card', {
+  props: {
+    name: { type: String, default: 'Guest' },
+    active: { type: Boolean }
+  },
+  template: `
+    <div class="card">
+      <h2 ref="title">{{ name }}</h2>
+      <span class="badge" hidden="">{{ active }}</span>
+    </div>
+  `,
+  on: {
+    connect({ refs }) {
+      refs.title.textContent = this.name;
+    },
+    change({ name, val, refs }) {
+      if (name === 'name') refs.title.textContent = val;
+    }
+  }
+});
+```
 
-You can separate a component's logical code, templates, and styles into separate files for clean maintainability. The compiler resolves the relative template and stylesheet paths, processes them, and emits them to `dist/`:
+Use it:
 
-### `ui-button/template.html`
 ```html
-<button class="btn" ref="button">
-  <slot></slot>
-</button>
+<user-card name="Alice" active></user-card>
 ```
 
-### `ui-button/style.css`
-```css
-:host { display: inline-block; }
-.btn { background: var(--color-primary); color: white; border: none; }
-```
+No build step. No JSX transform. No virtual DOM reconciliation. The browser parses the template, creates the DOM, and updates it when props change. Because that is literally what browsers are for.
 
-### `ui-button/index.js`
-```js
-import { ui } from '@adukiorg/anza/ui';
+### A Route
 
-ui.element('ui-button', {
-  template: './template.html',
-  style: './style.css',
-  props: {
-    disabled: { type: Boolean, default: false }
-  },
-  mount({ el, refs, on }) {
-    on.click('[ref="button"]', () => {
-      console.log('Button clicked!');
-    });
-  }
+```javascript
+import { page, dock } from '@adukiorg/anza/defs';
+
+dock('main', { parent: 'body' });
+
+page('/', {
+  tag: 'page-home',
+  via: ['main'],
+  template: { html: './home.html', css: './home.css' }
 }, import.meta.url);
 ```
 
----
-
-## Quick Examples
+Click `<a href="/about">`. The router intercepts it. The view transitions. No full page reload. The Navigation API has been in Chrome since 2022. We use it.
 
 ### Reactive State
 
-```js
+```javascript
 import { state } from '@adukiorg/anza/state';
 
-const store = state.create({ count: 0, theme: 'dark' });
+const store = state.create({ count: 0 });
 
 store.subscribe('count', () => {
   console.log('count changed to', store.get('count'));
 });
 
-store.set('count', 1);  // fires after microtask flush
-store.set('count', 2);  // batched — only one notification fires
+store.set('count', 1);
 ```
 
-### Network Requests
+Proxy-based reactivity. Batched updates. Cross-tab sync via `BroadcastChannel`. No reducers. No actions. No sagas. Just a store that notifies subscribers when data changes. Revolutionary, we know.
 
-```js
-import { api, PlatformError } from '@adukiorg/anza/api';
+### Theme Switching (Automatic)
 
-try {
-  const data = await api.get('https://api.example.com/posts');
-  console.log(data);
-} catch (err) {
-  if (err instanceof PlatformError) {
-    console.error(err.code, err.message); // 'NETWORK_TIMEOUT', 'HTTP_ERROR', etc.
-  }
-}
-```
+```javascript
+import { theme } from '@adukiorg/anza/theme';
 
-### IndexedDB Storage
+theme.toggle();        // light ↔ dark
+theme.set('contrast'); // high-contrast mode
+```
 
-```js
-import { Database } from '@adukiorg/anza/storage';
+No init call needed. It auto-restores from `localStorage` on import. Respects `prefers-color-scheme` if no saved preference exists. Attaches to `window.theme` for devtools access. Because theme toggles are not rocket science.
 
-const db = new Database('myapp', 1, [
-  (db) => db.createObjectStore('posts')
-]);
+---
 
-await db.open();
-await db.set('posts', 'post-1', { title: 'Hello', content: '...' });
-const post = await db.get('posts', 'post-1');
-```
+## The Token System
 
-### Animations
+Anza ships with a complete design token layer:
 
-```js
-import { animate, stagger } from '@adukiorg/anza/animations';
+- **Primitives** — OKLCH color scales, spacing, motion, radius, shadow, z-index
+- **Semantic** — light, dark, high-contrast themes with GPU-accelerated token morphing
+- **Components** — form controls, feedback, overlays, layout tokens
+- **Transitions** — View Transition timing and backdrop tokens
 
-// Single element
-animate(el, [{ opacity: 0 }, { opacity: 1 }], { duration: 300 });
+You own `src/tokens/` after scaffolding. Change a primitive, every component updates. Change a semantic mapping, the whole theme shifts. Override anything in `@layer overrides`. The cascade handles the rest.
 
-// Staggered group
-const cards = document.querySelectorAll('.card');
-stagger(Array.from(cards), [
-  { transform: 'translateY(20px)', opacity: 0 },
-  { transform: 'translateY(0)',    opacity: 1 }
-], { duration: 250, staggerDelay: 60 });
-```
+---
 
-### Client-Side Router
+## Philosophy
 
-```js
-import { register, navigate } from '@adukiorg/anza/router';
+**Native first.** If the browser has an API for it, we use it. If it doesn't, we build the smallest possible wrapper. We do not reimplement the browser inside JavaScript.
 
-register('/posts/:id', async ({ params }) => {
-  const post = await fetchPost(params.id);
-  renderPost(post);
-});
+**Zero build.** The browser resolves ESM imports natively. Our Rust CLI copies the files you use into `dist/`. That is the whole build step. No bundling. No tree-shaking algorithms. The browser is single-threaded anyway.
 
-navigate('/posts/42');
-```
+**You own your code.** Scaffolding copies starter files into `src/`. The library never touches them again. No hidden configs. No magic globals. No runtime injection of framework internals.
 
 ---
 
 ## Testing
 
-Tests run in **real Chromium** via `@web/test-runner` — no jsdom or node mocks.
+Tests run in **real Chromium** via `@web/test-runner` — no jsdom, no node mocks, no pretend browser.
 
 ```bash
-cd library
 npm test
 ```
 
+If it passes in Chromium, it passes in Chrome. If it passes in Chrome, it probably works everywhere else. (We said probably. Safari is Safari.)
+
 ---
 
 ## License

package/bin/anza/find.js

@@ -0,0 +1,35 @@
+/**
+ * bin/anza/find.js
+ *
+ * Resolves the anza Rust binary path for the current platform.
+ */
+
+import { join } from 'path';
+import { existsSync } from 'fs';
+
+const PLATFORMS = {
+  darwin: { x64: 'anza-macos-x64', arm64: 'anza-macos-arm64' },
+  linux:  { x64: 'anza-linux-x64', arm64: 'anza-linux-arm64' },
+  win32:  { x64: 'anza-windows-x64.exe', arm64: 'anza-windows-arm64.exe' },
+};
+
+export function resolve(root, here) {
+  const dev = join(root, 'tools', 'target', 'release', 'anza');
+  if (existsSync(dev)) return dev;
+
+  const platform = process.platform;
+  const arch = process.arch;
+  const name = PLATFORMS[platform]?.[arch];
+
+  if (!name) {
+    throw new Error(`Unsupported platform: ${platform} ${arch}`);
+  }
+
+  const prebuilt = join(here, name);
+  if (existsSync(prebuilt)) return prebuilt;
+
+  throw new Error(
+    'anza binary not found.\n' +
+    'Run: node tasks/build.js  (from the repo root)'
+  );
+}

package/bin/anza/index.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * bin/anza/index.js
+ *
+ * Node.js wrapper for the anza Rust binary.
+ * Re-exports find and launch for programmatic use.
+ */
+
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { resolve } from './find.js';
+import { start } from './launch.js';
+
+export { resolve } from './find.js';
+export { start } from './launch.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname  = dirname(__filename);
+
+const library = join(__dirname, '..', '..');
+const root    = join(library, '..');
+
+// CLI entry only when executed directly
+const isCli = process.argv[1] === __filename;
+
+if (isCli) {
+  try {
+    const path = resolve(root, __dirname);
+    start(path, process.argv.slice(2));
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+}

package/bin/anza/launch.js

@@ -0,0 +1,19 @@
+/**
+ * bin/anza/launch.js
+ *
+ * Spawns the anza Rust binary with forwarded args.
+ */
+
+import { spawn } from 'child_process';
+import * as logs from '../common/index.js';
+
+export function start(path, args) {
+  const child = spawn(path, args, { stdio: 'inherit' });
+
+  child.on('error', (err) => {
+    logs.error(`Failed to spawn anza: ${err.message}`);
+    process.exit(1);
+  });
+
+  child.on('exit', (code) => process.exit(code ?? 0));
+}

package/bin/common/index.js

@@ -0,0 +1,7 @@
+/**
+ * bin/common/index.js
+ *
+ * Re-exports the logs module for cleaner imports.
+ */
+
+export * from './logs.js';

package/bin/common/logs.js

@@ -0,0 +1,62 @@
+/**
+ * bin/common/logs.js
+ *
+ * Colored category logger matching the Rust logs crate.
+ * Categories: info, debug, success, error, warn, compiler, server, hmr, watcher, sync.
+ */
+
+const RESET  = '\x1b[0m';
+const GRAY   = '\x1b[90m';
+const BLUE   = '\x1b[34m';
+const CYAN   = '\x1b[36m';
+const GREEN  = '\x1b[1m\x1b[32m';
+const RED    = '\x1b[1m\x1b[31m';
+const YELLOW = '\x1b[1m\x1b[33m';
+const BYELLOW = '\x1b[93m';
+const BBLUE  = '\x1b[94m';
+const BGREEN = '\x1b[92m';
+
+function stamp() {
+  const d = new Date();
+  return `${GRAY}[${d.toISOString().slice(0, 19).replace('T', ' ')}]${RESET} `;
+}
+
+export function info(msg) {
+  console.log(`${stamp()}${BLUE}INFO:${RESET} ${msg}`);
+}
+
+export function debug(msg) {
+  console.log(`${stamp()}${GRAY}DEBUG:${RESET} ${msg}`);
+}
+
+export function success(msg) {
+  console.log(`${stamp()}${GREEN}SUCCESS:${RESET} ${msg}`);
+}
+
+export function error(msg) {
+  console.error(`${stamp()}${RED}ERROR:${RESET} ${msg}`);
+}
+
+export function warn(msg) {
+  console.warn(`${stamp()}${YELLOW}WARN:${RESET} ${msg}`);
+}
+
+export function compiler(msg) {
+  console.log(`${stamp()}${CYAN}COMPILER:${RESET} ${msg}`);
+}
+
+export function server(msg) {
+  console.log(`${stamp()}${BBLUE}SERVER:${RESET} ${msg}`);
+}
+
+export function hmr(msg) {
+  console.log(`${stamp()}${BGREEN}HMR:${RESET} ${msg}`);
+}
+
+export function watcher(msg) {
+  console.log(`${stamp()}${BYELLOW}WATCHER:${RESET} ${msg}`);
+}
+
+export function sync(msg) {
+  console.log(`${stamp()}${GRAY}SYNC:${RESET} ${msg}`);
+}

package/bin/create/copy.js

@@ -0,0 +1,18 @@
+/**
+ * bin/create/copy.js
+ *
+ * Recursively copies a directory tree.
+ */
+
+import { cpSync } from 'fs';
+import * as logs from '../common/index.js';
+
+export function copy(src, dst) {
+  try {
+    cpSync(src, dst, { recursive: true });
+    return true;
+  } catch (e) {
+    logs.warn(`Could not copy ${src} -> ${dst}: ${e.message}`);
+    return false;
+  }
+}

package/bin/create/index.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/**
+ * bin/create/index.js
+ *
+ * Scaffolds a new anza app project in the given directory.
+ * Re-exports run, copy, and write for programmatic use.
+ */
+
+import { resolve, basename, dirname, join } from 'path';
+import { existsSync } from 'fs';
+import { fileURLToPath } from 'url';
+import * as logs from '../common/index.js';
+import { run } from './run.js';
+
+export { run } from './run.js';
+export { copy } from './copy.js';
+export { write } from './write.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname  = dirname(__filename);
+
+const arg = process.argv[2];
+
+// CLI entry only when executed directly
+const isCli = process.argv[1] === __filename;
+
+if (isCli) {
+  if (!arg || arg === '--help' || arg === '-h') {
+    console.log('Usage: npx anza-create <name>');
+    console.log('       npx anza-create .     (scaffold in current dir)');
+    process.exit(arg ? 0 : 1);
+  }
+
+  const target = resolve(arg);
+  const name   = arg === '.' ? basename(process.cwd()) : basename(target);
+
+  if (existsSync(target) && arg !== '.') {
+    logs.error(`'${target}' already exists.`);
+    process.exit(1);
+  }
+
+  const library = join(__dirname, '..', '..');
+
+  run(target, name, library);
+}