slicejs-cli 3.5.1 → 3.6.0

package/AGENTS.md

@@ -1,247 +0,0 @@
-# Slice.js CLI — Agent Context
-
-## Project Structure
-
-```
-slicejs-cli/
-├── client.js                          # CLI entry point (commander)
-├── commands/
-│   ├── init/init.js                   # slice init
-│   ├── startServer/startServer.js     # slice dev / slice start
-│   ├── build/build.js                 # slice build
-│   ├── getComponent/getComponent.js   # slice get / browse / sync
-│   ├── createComponent/               # slice component create
-│   ├── listComponents/                # slice component list
-│   ├── deleteComponent/                # slice component delete
-│   ├── doctor/doctor.js               # slice doctor
-│   ├── types/types.js                 # slice types generate
-│   ├── bundle/bundle.js               # bundling logic
-│   ├── utils/
-│   │   ├── PathHelper.js              # Path resolution (critical)
-│   │   ├── bundling/BundleGenerator.js
-│   │   ├── updateManager.js
-│   │   ├── VersionChecker.js
-│   │   └── LocalCliDelegation.js
-│   └── Print.js                       # Wrapper for console.log/error
-├── tests/
-│   ├── helpers/setup.js               # Shared test helper (createTestProject, withTestProject)
-│   ├── fixtures/                      # Minimal fixture files for tests
-│   ├── bundle-generator.test.js
-│   ├── bundle-v2-register-output.test.js
-│   ├── client-launcher-contract.test.js
-│   ├── client-update-flow-contract.test.js
-│   ├── component-registry-parse.test.js
-│   ├── dependency-analyzer.test.js
-│   ├── init-command-contract.test.js
-│   ├── local-cli-delegation.test.js
-│   ├── path-helper.test.js
-│   ├── postinstall-command.test.js
-│   ├── types-generator.test.js
-│   └── update-manager-notifications.test.js
-├── package.json                       # type: "module" — ES modules only
-└── AGENTS.md                          # This file
-```
-
-## Testing System
-
-### Runner
-- Uses Node.js built-in test runner: `node --test`
-- Run: `npm test`
-- Watch mode: `node --test --watch`
-
-### Shared Test Helper (`tests/helpers/setup.js`)
-Three exported functions:
-
-```js
-import { createTestProject, cleanupTestProject, withTestProject } from './helpers/setup.js';
-```
-
-**`createTestProject(options)`** — Creates a temp directory with full Slice.js project scaffold.
-- Copies real framework files from `../slice.js/` (sibling directory in monorepo)
-- Falls back to `tests/fixtures/` minimal scaffold if framework not available
-- Options:
-  - `visualComponents: ['Button']` — creates stub component files + rewrites `components.js` to include only those
-  - `frameworkDir` — custom framework source path
-- Returns the temp directory path
-- Temp dir path: `{os.tmpdir()}/slice-test-{PID}-{N}-{random}/`
-
-**`cleanupTestProject(dir)`** — Removes the temp directory recursively.
-
-**`withTestProject(fn, options)`** — Convenience wrapper that:
-1. Calls `createTestProject(options)`
-2. Saves and sets `process.env.INIT_CWD = dir`
-3. Runs `fn(dir)`
-4. Restores `process.env.INIT_CWD` to original value
-5. Calls `cleanupTestProject(dir)` in `finally`
-
-### Patterns
-
-**For tests that need INIT_CWD pointing to the project:**
-```js
-test('my test', async () => {
-  await withTestProject(async (tmpDir) => {
-    // process.env.INIT_CWD is already set to tmpDir
-    const result = someFunction(import.meta.url);
-    assert.ok(result);
-  });
-});
-```
-
-**For tests that pass projectRoot explicitly:**
-```js
-test('my test', async () => {
-  const tmpRoot = await createTestProject({ visualComponents: ['Button'] });
-  try {
-    const result = await someFunction({ projectRoot: tmpRoot });
-    assert.equal(result, 1);
-  } finally {
-    await cleanupTestProject(tmpRoot);
-  }
-});
-```
-
-**For tests with shared project setup across a describe block:**
-```js
-let tmpRoot;
-before(async () => {
-  tmpRoot = await createTestProject();
-  process.env.INIT_CWD = tmpRoot;
-});
-after(async () => {
-  delete process.env.INIT_CWD;
-  await cleanupTestProject(tmpRoot);
-});
-```
-
-### Test types
-
-1. **Contract tests** (`*-contract.test.js`) — Static analysis of `client.js` source code via `@babel/parser` + AST or regex. Verify command registration, option flags, and function calls. No runtime execution.
-2. **Unit tests** — Test individual functions/modules in isolation. Use temp dirs for filesystem-dependent code.
-3. **Snapshot/Integration tests** — Verify output files, generated declarations, bundle configs.
-
-### Rules
-- No external mocking libraries (sinon, jest, etc.). Use monkey-patching + try/finally restore.
-- All temp dirs MUST be cleaned up in `finally` blocks.
-- `process.env.INIT_CWD` must be saved before modification and restored in `finally`.
-- Dynamic `import()` is used where module caching matters, but PathHelper reads env vars at call time so cached modules work correctly.
-
-## PathHelper Rules (`commands/utils/PathHelper.js`)
-
-### Project Root Resolution
-`getProjectRoot(moduleUrl)` resolves in this order:
-1. `process.env.INIT_CWD` — set by npm or by `withTestProject` during tests
-2. `process.cwd()` — current working directory
-3. `candidates(moduleUrl)` — heuristic: walk up `../../` and `../../../../` from module location, check for `src/` or `api/`
-
-### Functions
-
-| Function | Returns | Notes |
-|---|---|---|
-| `getProjectRoot(moduleUrl)` | Resolved project root path | |
-| `getSrcPath(moduleUrl, ...seg)` | `<root>/src/[...seg]` | |
-| `getApiPath(moduleUrl, ...seg)` | `<root>/api/[...seg]` | |
-| `getDistPath(moduleUrl, ...seg)` | `<root>/dist/[...seg]` | |
-| `getPath(moduleUrl, ...seg)` | `<root>/[...seg]` | General purpose |
-| `getConfigPath(moduleUrl, root?)` | `src/sliceConfig.json` | Optional explicit root param |
-| `getComponentsJsPath(moduleUrl, root?)` | `src/Components/components.js` | Optional explicit root param |
-| `joinRoot(root, ...seg)` | `<root>/[...seg]` | No moduleUrl needed, pure path join |
-
-### Critical Rules
-
-1. **`import.meta.url` must be passed** as first argument to all PathHelper functions (except `joinRoot`).
-2. **Explicit root parameter** (`getConfigPath`, `getComponentsJsPath`) is used by `types/types.js` when generating types for a non-cwd project. This keeps functions testable without global state.
-3. **`INIT_CWD` is the primary mechanism** for project root resolution. It's set by npm lifecycle scripts and by `withTestProject`.
-4. **`candidates()` fallback** only works when the CLI is installed inside a project that has `src/` or `api/`. This is intentionally limited.
-
-## Code Quality Standards
-
-### ES Modules Only
-- `"type": "module"` in `package.json`
-- Use `import`/`export` everywhere
-- NO `require()`, NO `__dirname` at module scope (use `path.dirname(fileURLToPath(import.meta.url))` inline where needed)
-
-### No eval()
-- `eval()` has been fully replaced with `JSON.parse()` for reading `components.js` files
-- Components are written via `JSON.stringify()`, so content is always valid JSON
-- Use `JSON.parse()` or the AST-based `ComponentRegistry` for component registry parsing
-
-### Error Messages
-- Bare error messages (just the error message without context) must NOT be used
-- Always wrap errors with context: `Print.error('Context:', error.message)`
-- Use `Print.error()` / `Print.success()` / `Print.info()` / `Print.warning()` instead of raw `console.log`/`console.error`
-- EXCEPTION: Formatted help/command listing output can use `console.log` directly (avoids `ℹ️ Info:` prefix pollution)
-
-### Empty Catch Blocks
-- Silent catches are acceptable ONLY for:
-  - Non-critical operations (update checks, optional config reads)
-  - Graceful degradation paths
-- All silent catches MUST have a comment explaining why: `catch { /* intentional: non-critical */ }`
-
-### Port Resolution (startServer)
-Priority order:
-1. `--port` CLI flag (if provided by user)
-2. `config.server.port` from `sliceConfig.json`
-3. Hardcoded `3000` fallback
-
-Commander `.option()` defaults must NOT override config values. Pass `undefined` when flag is not provided:
-```js
-port: options.port ? parseInt(options.port) : undefined
-```
-
-### Dependency Injection for Testability
-- Functions that need a project root accept it as a parameter (`projectRoot`, `root`)
-- PathHelper functions that accept an explicit root param enable testing without INIT_CWD gymnastics
-- Avoid reading `process.env.INIT_CWD` or `process.cwd()` directly inside business logic; use PathHelper
-
-## CLI Architecture (client.js)
-
-### Command Registration Pattern
-```js
-sliceClient
-  .command("mycommand")
-  .description("...")
-  .option("-x, --flag <value>", "...")
-  .action(async (options) => {
-    // 1. Handle --yes / non-interactive flags before prompts
-    // 2. Prompt for missing required values
-    // 3. Delegate to command implementation
-    await runWithVersionCheck(async () => {
-      await myCommandImplementation(options);
-    });
-  });
-```
-
-### `runWithVersionCheck(commandFunction)`
-- Wraps every command action
-- Responsibilities:
-  1. Fire-and-forget update notification (`notifyAvailableUpdates().catch(() => {})`)
-  2. Execute the command
-  3. Background version check (`checkForUpdates(false)` after 100ms delay)
-- Does NOT block or prompt the user (pre-flight checks were removed)
-- Errors are caught and logged via `Print.error()`
-
-### Init Command (`slice init`)
-- Default project name: `my-slice-app`
-- `-y`/`--yes [name]` flag skips interactive prompts
-- Creates project directory, `chdir`s into it, sets `INIT_CWD`
-- Calls `initializeProject()` from `commands/init/init.js`
-- Name normalization: trim → lowercase → spaces to hyphens → strip non-alphanumeric → collapse hyphens → trim hyphens
-
-### Local CLI Delegation
-- `maybeDelegateToLocalCli()` runs at module level before command parsing
-- If a local `node_modules/slicejs-cli/` exists, spawns it instead of running the global CLI
-- Controlled by `SLICE_NO_LOCAL_DELEGATION` env var
-
-## Visual Component Registry
-- Components downloaded from GitHub: `https://raw.githubusercontent.com/VKneider/slice.js_visual_library/master/src/Components/{category}/{Name}/{file}`
-- Registry URL: same base + `src/Components/components.js`
-- Starter visual components on init: Button, Link, Loading, MultiRoute, Navbar, NotFound, Route
-- Components are registered by writing to `src/Components/components.js`
-
-### File Download Rules (in `getAvailableComponents`)
-- **Routing/navigation components** (`Route`, `MultiRoute`, `Link`): only `.js` file
-- **Other Visual components** (Button, Loading, Navbar, etc.): `.js`, `.html`, `.css`
-- **Service components** (FetchManager, etc.): only `.js` file
-- File list is determined by hardcoded rules, NOT by checking the remote server
-- If `.js` download fails → component install fails (fatal)
-- If `.html`/`.css` fails → component install succeeds with warning

package/CODE_OF_CONDUCT.md

@@ -1,126 +0,0 @@
-# Contributor Covenant Code of Conduct
-
-## Our Pledge
-
-We as members, contributors, and leaders pledge to make participation in our
-community a harassment-free experience for everyone, regardless of age, body
-size, visible or invisible disability, ethnicity, sex characteristics, gender
-identity and expression, level of experience, education, socio-economic status,
-nationality, personal appearance, race, caste, color, religion, or sexual
-identity and orientation.
-
-We pledge to act and interact in ways that contribute to an open, welcoming,
-diverse, inclusive, and healthy community.
-
-## Our Standards
-
-Examples of behavior that contributes to a positive environment for our
-community include:
-
-* Demonstrating empathy and kindness toward other people
-* Being respectful of differing opinions, viewpoints, and experiences
-* Giving and gracefully accepting constructive feedback
-* Accepting responsibility and apologizing to those affected by our mistakes,
-  and learning from the experience
-* Focusing on what is best not just for us as individuals, but for the
-  overall community
-
-Examples of unacceptable behavior include:
-
-* The use of sexualized language or imagery, and sexual attention or
-  advances of any kind
-* Trolling, insulting or derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or email
-  address, without their explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
-  professional setting
-
-## Enforcement Responsibilities
-
-Community leaders are responsible for clarifying and enforcing our standards of
-acceptable behavior and will take appropriate and fair corrective action in
-response to any behavior that they deem inappropriate, threatening, offensive,
-or harmful.
-
-Community leaders have the right and responsibility to remove, edit, or reject
-comments, commits, code, wiki edits, issues, and other contributions that are
-not aligned to this Code of Conduct, and will communicate reasons for moderation
-decisions when appropriate.
-
-## Scope
-
-This Code of Conduct applies within all community spaces, and also applies when
-an individual is officially representing the community in public spaces.
-Examples of representing our community include using an official e-mail address,
-posting via an official social media account, or acting as an appointed
-representative at an online or offline event.
-
-## Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported to Victor Kneider at vkneider.dev@gmail.com or via LinkedIn
-(https://www.linkedin.com/in/vkneider/). All complaints will be reviewed and investigated
-promptly and fairly.
-
-All community leaders are obligated to respect the privacy and security of the
-reporter of any incident.
-
-## Enforcement Guidelines
-
-Community leaders will follow these Community Impact Guidelines in determining
-the consequences for any action they deem in violation of this Code of Conduct:
-
-### 1. Correction
-
-**Community Impact**: Use of inappropriate language or other behavior deemed
-unprofessional or unwelcome in the community.
-
-**Consequence**: A private, written warning from community leaders, providing
-clarity around the nature of the violation and an explanation of why the
-behavior was inappropriate. A public apology may be requested.
-
-### 2. Warning
-
-**Community Impact**: A violation through a single incident or series of
-actions.
-
-**Consequence**: A warning with consequences for continued behavior. No
-interaction with the people involved, including unsolicited interaction with
-those enforcing the Code of Conduct, for a specified period of time. This
-includes avoiding interactions in community spaces as well as external channels
-like social media. Violating these terms may lead to a temporary or permanent
-ban.
-
-### 3. Temporary Ban
-
-**Community Impact**: A serious violation of community standards, including
-sustained inappropriate behavior.
-
-**Consequence**: A temporary ban from any sort of interaction or public
-communication with the community for a specified period of time. No public or
-private interaction with the people involved, including unsolicited interaction
-with those enforcing the Code of Conduct, is allowed during this period.
-Violating these terms may lead to a permanent ban.
-
-### 4. Permanent Ban
-
-**Community Impact**: Demonstrating a pattern of violation of community
-standards, including sustained inappropriate behavior, harassment of an
-individual, or aggression toward or disparagement of classes of individuals.
-
-**Consequence**: A permanent ban from any sort of public interaction within
-the community.
-
-## Attribution
-
-This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
-version 2.1, available at
-https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
-
-Community Impact Guidelines were inspired by [Mozilla's code of conduct
-enforcement ladder](https://github.com/mozilla/diversity).
-
-For answers to common questions about this code of conduct, see the FAQ at
-https://www.contributor-covenant.org/faq. Translations are available at
-https://www.contributor-covenant.org/translations.

package/ECOSYSTEM.md

@@ -1,9 +0,0 @@
-# Slice.js Ecosystem
-
-| Repository | Description | URL |
-|---|---|---|
-| slice.js | Core web framework | https://github.com/VKneider/slice.js |
-| slice-cli | CLI tool for project management | https://github.com/VKneider/slicejs-cli |
-| slice.js_visual_library | Official visual components and docs | https://github.com/VKneider/slice.js_visual_library |
-| sliceDocs | Framework documentation site | https://github.com/VKneider/slicejs_docs |
-| PortfolioVK2 | Portfolio and demo app | https://github.com/VKneider/portfolio |

package/docs/superpowers/specs/2026-05-10-pwa-generate-design.md

@@ -1,182 +0,0 @@
-# Design of `slice generate-pwa` (V1)
-
-## Objective
-
-Add a dedicated CLI command, `slice generate-pwa`, that converts a Slice build into an offline-capable PWA, with configurable cache strategy and explicit backend domain exclusion to prevent accidental REST API caching.
-
-The command must be post-bundle, operate on `dist/`, and maintain a simple V1 experience.
-
-## V1 Scope
-
-- New `slice generate-pwa` command.
-- Automatically run `build` before the PWA process.
-- Generate `manifest.json` in `dist/`.
-- Generate `sw.js` in `dist/`.
-- Register Service Worker in the entry HTML of `dist`.
-- Support strategies: `hybrid` (default), `offline-first`, `network-first`.
-- Persist and read configuration from `src/sliceConfig.json` in:
-  - `pwa.cache.excludeDomains`.
-- Apply effective exclusion of `localhost` and `127.0.0.1` in development.
-
-## Out of V1 Scope
-
-- Exclusion by paths or headers (`excludePaths`, `excludeHeaders`).
-- Advanced interactive UI for creating PWA icons.
-- Support for push notifications, background sync, or advanced runtime caching by API type.
-- Formal plugin system; left prepared for future evolution.
-
-## Command UX
-
-### Syntax
-
-```bash
-slice generate-pwa
-slice generate-pwa --strategy hybrid
-slice generate-pwa --strategy offline-first
-slice generate-pwa --strategy network-first
-slice generate-pwa --name "My App" --short-name "MyApp"
-```
-
-### V1 Flags
-
-- `--strategy <hybrid|offline-first|network-first>` (default: `hybrid`)
-- `--name <string>`
-- `--short-name <string>`
-
-### Execution flow
-
-1. Run production build.
-2. Read and normalize PWA configuration from `src/sliceConfig.json`.
-3. Generate asset manifest for precache from `dist/`.
-4. Generate `dist/manifest.json`.
-5. Generate `dist/sw.js` with the selected strategy.
-6. Inject (or ensure) SW registration in entry HTML of `dist`.
-7. Print final summary:
-   - strategy used,
-   - number of precached assets,
-   - effective excluded domains.
-
-## Configuration in `sliceConfig.json`
-
-V1 minimal section:
-
-```json
-{
-  "pwa": {
-    "cache": {
-      "excludeDomains": []
-    }
-  }
-}
-```
-
-Rules:
-
-- If `pwa` does not exist, the command creates the section without breaking existing configuration.
-- `excludeDomains` accepts exact hosts (e.g., `api.mydomain.com`).
-- In development execution, `localhost` and `127.0.0.1` are effectively added (not necessarily persisted).
-
-## Proposed Architecture
-
-### CLI Integration
-
-- Add command in `client.js`:
-  - `generate-pwa`
-  - `--strategy` option
-  - name options for manifest
-
-### New Modules
-
-- `commands/pwa/generatePwa.js`
-  - Orchestrator of the complete flow.
-- `commands/pwa/ConfigResolver.js`
-  - Reads/creates/normalizes `pwa.cache.excludeDomains`.
-- `commands/pwa/AssetManifestBuilder.js`
-  - Iterates `dist/` and builds precache list.
-- `commands/pwa/ManifestGenerator.js`
-  - Generates `manifest.json` with defaults and flag overrides.
-- `commands/pwa/ServiceWorkerGenerator.js`
-  - Generates `sw.js` with selected strategy and exclusions.
-
-## Cache Design
-
-### Global Rules
-
-- Intercept only `GET` requests.
-- If the host is in `excludeDomains`, do a direct `fetch` (no cache).
-- Cache versioning by build id (timestamp or build hash).
-- On new SW activation, automatically clean old caches.
-
-### Strategies
-
-- `hybrid` (default):
-  - static assets -> `cache-first`.
-  - HTML navigation -> `network-first` with offline fallback.
-- `offline-first`:
-  - navigation + static -> `cache-first`.
-  - background update when online.
-- `network-first`:
-  - navigation -> `network-first`.
-  - precached static assets as fallback.
-
-## REST API and Security Handling
-
-To prevent unwanted backend caching:
-
-- Domain exclusion via `excludeDomains` (main V1 rule).
-- Limit runtime cache to frontend assets and navigation per strategy.
-- Do not cache methods other than `GET`.
-
-Result: client assets are accelerated offline, but the backend stays out of the cache via explicit configuration.
-
-## Error handling
-
-- If build fails, abort `generate-pwa` with a clear message.
-- If `dist/` does not exist after build, abort with diagnostics.
-- If `sliceConfig.json` is invalid, show error with repair suggestion.
-- If SW registration cannot be injected into HTML, report warning and target path.
-
-## Testing
-
-### Unit tests
-
-- `ConfigResolver`:
-  - creates `pwa.cache.excludeDomains` section when it does not exist,
-  - respects existing config.
-- `AssetManifestBuilder`:
-  - includes expected assets,
-  - excludes unsuitable files.
-- `ServiceWorkerGenerator`:
-  - generates correct logic per strategy,
-  - respects `excludeDomains`.
-
-### Integration
-
-- `slice generate-pwa` runs build and creates `dist/manifest.json` + `dist/sw.js`.
-- SW registration present in output HTML.
-- domain exclusions applied in generated code.
-
-### Minimal E2E manual
-
-- Build + generate-pwa.
-- Open app, validate installability (manifest).
-- Turn off network, validate offline navigation in `hybrid`.
-- Verify that requests to excluded domain are not served from SW cache.
-
-## Evolution Plan (post V1)
-
-- `excludePaths` and `excludeHeaders`.
-- Assisted PWA icon and shortcut support.
-- Per-route strategy (e.g., `/api/*` network-only).
-- Extract reusable postbundle pipeline for other features.
-
-## Acceptance Criteria
-
-- Functional `slice generate-pwa` command exists.
-- Runs build before generating PWA artifacts.
-- Generates `manifest.json` and `sw.js` in `dist/`.
-- Registers SW in main output HTML.
-- `hybrid` is default with HTML `network-first` and offline fallback.
-- Reads/writes `pwa.cache.excludeDomains` in `src/sliceConfig.json`.
-- Excludes configured domains from runtime cache.
-- Shows a readable final summary to the user.

package/playwright.config.js

@@ -1,51 +0,0 @@
-import { defineConfig, devices } from '@playwright/test';
-
-const PORT = process.env.E2E_PORT ? Number(process.env.E2E_PORT) : 3210;
-const UNMIN_PORT = PORT + 4;
-const BASE_URL = `http://127.0.0.1:${PORT}`;
-const UNMIN_URL = `http://127.0.0.1:${UNMIN_PORT}`;
-
-export default defineConfig({
-  testDir: './tests/e2e',
-  testMatch: '**/*.spec.js',
-  fullyParallel: false,
-  workers: 1,
-  timeout: 30_000,
-  expect: { timeout: 10_000 },
-  reporter: process.env.CI ? [['list'], ['html', { open: 'never' }]] : [['list']],
-  use: {
-    trace: 'retain-on-failure',
-  },
-  projects: [
-    {
-      name: 'chromium',
-      testIgnore: '**/unminified.spec.js',
-      use: { ...devices['Desktop Chrome'], baseURL: BASE_URL },
-    },
-    {
-      name: 'chromium-unminified',
-      testMatch: '**/unminified.spec.js',
-      use: { ...devices['Desktop Chrome'], baseURL: UNMIN_URL },
-    },
-  ],
-  webServer: [
-    {
-      command: 'node tests/e2e/serve.mjs',
-      url: `${BASE_URL}/slice-env.json`,
-      env: { E2E_PORT: String(PORT) },
-      timeout: 120_000,
-      reuseExistingServer: !process.env.CI,
-      stdout: 'pipe',
-      stderr: 'pipe',
-    },
-    {
-      command: 'node tests/e2e/serve.mjs',
-      url: `${UNMIN_URL}/slice-env.json`,
-      env: { E2E_PORT: String(UNMIN_PORT), E2E_MINIFY: 'false' },
-      timeout: 120_000,
-      reuseExistingServer: !process.env.CI,
-      stdout: 'pipe',
-      stderr: 'pipe',
-    },
-  ],
-});