@jahia/jahia-cli 0.1.4 → 0.3.0

package/README.md

@@ -17,36 +17,266 @@ npm install -g @jahia/jahia-cli
 ### Via npx (no installation)
 
 ```bash
-npx @jahia/jahia-cli hello
+npx @jahia/jahia-cli environment create --component jahia --component pgsql
 ```
 
-## Usage
+### Via Docker
 
 ```bash
-# Display help
-jahia --help
+docker run --rm -v /var/run/docker.sock:/var/run/docker.sock ghcr.io/jahia/jahia-cli environment list
+```
+
+## Quick Start
+
+```bash
+# Create a Jahia environment with PostgreSQL
+jahia-cli environment create --component jahia --component pgsql
+
+# Check environment health
+jahia-cli environment doctor
+
+# View logs from a component
+jahia-cli environment logs --component jahia
+
+# List all components and their status
+jahia-cli environment list
 
-# Run the hello command
-jahia hello
+# Stop the environment (preserves containers)
+jahia-cli environment stop
 
-# Greet someone by name
-jahia hello YourName
+# Restart the environment
+jahia-cli environment start
 
-# Uppercase greeting
-jahia hello --uppercase
+# Destroy everything
+jahia-cli environment delete
 ```
 
 ## Commands
 
-### `jahia hello [NAME]`
+### `config init`
+
+Generate an initialized Jahia CLI configuration file.
+
+```bash
+# Derive config from active state
+jahia-cli config init
+
+# Generate a blank scaffold
+jahia-cli config init --blank
+
+# Use custom state file and output path
+jahia-cli config init --state ~/.jahia-cli/state.json --output ./my-config.yml
+
+# Overwrite existing file
+jahia-cli config init --force
+```
+
+**Flags:**
+- `--state` - Path to state JSON file used for state-derived config
+- `-o, --output` - Output YAML file path (default: `jahia-cli.config.yml`)
+- `--blank` - Generate a blank scaffold instead of deriving from state
+- `-f, --force` - Overwrite output file if it already exists
+- `--json` - Structured JSON output
+
+### `tests init`
+
+Initialize local test scaffolding from `Jahia/jahia-cypress`.
+
+This command clones `jahia-cypress` at the specified version (branch/tag), or the latest tag
+when version is omitted, reads `scaffolding/`, and recursively copies only missing files into
+your local tests folder. Existing local files are kept as-is.
+
+If `<tests-folder>/config.yml` does not exist, it is initialized and seeded with:
+
+```yaml
+tests:
+  jahia-cypress: <resolved-version>
+```
+
+```bash
+# Initialize from latest jahia-cypress tag
+jahia-cli tests init
+
+# Initialize tests folder from a working branch
+jahia-cli tests init test-jahia-cli
+
+# Use a release tag and a custom destination
+jahia-cli tests init v1.2.3 ./tests
 
-Say hello from Jahia CLI.
+# Use custom destination without specifying version
+jahia-cli tests init --path ./tests
+
+# JSON output for CI/AI
+jahia-cli tests init main tests --json
+```
 
 **Arguments:**
-- `NAME` — Name to greet (default: `world`)
+- `[version]` - Branch or tag to fetch from `Jahia/jahia-cypress` (default: latest tag)
+- `[path]` - Local tests folder path (default: `tests`)
+
+**Flags:**
+- `-p, --path` - Local tests folder path (overrides positional path)
+- `--json` - Structured JSON output
+
+### `environment create`
+
+Create a new Jahia environment from predefined components.
+
+```bash
+# Interactive mode (prompts for component selection)
+jahia-cli environment create
+
+# Specify components directly
+jahia-cli environment create --component jahia --component pgsql --component elasticsearch
+
+# Use a YAML config file
+jahia-cli environment create --config ./my-environment.yml
+
+# Named environment with JSON output (for AI agents)
+jahia-cli environment create --name my-env --component jahia --component pgsql --json
+
+# Force-replace an existing environment
+jahia-cli environment create --component jahia --force
+```
 
 **Flags:**
-- `-u, --uppercase` — Transform the greeting to uppercase
+- `-C, --component` — Component to include (repeatable)
+- `-c, --config` — Path to a YAML configuration file
+- `-n, --name` — Environment name (auto-generated if omitted)
+- `-p, --provider` — Provider to use (default: `docker`)
+- `-f, --force` — Delete existing environment before creating
+- `--json` — Structured JSON output
+
+### `environment stop`
+
+Stop a running environment without destroying it.
+
+```bash
+jahia-cli environment stop
+jahia-cli environment stop --json
+```
+
+### `environment start`
+
+Restart a previously stopped environment.
+
+```bash
+jahia-cli environment start
+jahia-cli environment start --json
+```
+
+### `environment delete`
+
+Destroy an environment completely (containers, networks, volumes).
+
+```bash
+jahia-cli environment delete
+jahia-cli environment delete --json
+```
+
+### `environment doctor`
+
+Check health status of the active environment.
+
+```bash
+jahia-cli environment doctor
+jahia-cli environment doctor --name my-env --json
+```
+
+### `environment logs`
+
+View logs from a specific component.
+
+```bash
+jahia-cli environment logs --component jahia
+jahia-cli environment logs --component pgsql --tail 50
+jahia-cli environment logs --component jahia --json
+```
+
+**Flags:**
+- `-C, --component` — Component to show logs for (required)
+- `-t, --tail` — Number of lines from the end (default: 100)
+- `--json` — Structured JSON output
+
+### `environment list`
+
+Show all components and their live status.
+
+```bash
+jahia-cli environment list
+jahia-cli environment list --json
+```
+
+## Available Components
+
+| Component | Description |
+|-----------|-------------|
+| `jahia` | Jahia DXM processing node |
+| `jahia-browsing` | Jahia browsing (read-only) node |
+| `pgsql` | PostgreSQL database |
+| `elasticsearch` | Elasticsearch search engine |
+
+## YAML Configuration
+
+Create a `environment.yml` file to define complex environments:
+
+```yaml
+name: my-jahia-env
+provider: docker
+components:
+  - jahia
+  - pgsql
+  - name: elasticsearch
+    overrides:
+      tag: "8.11.0"
+tests:
+  jahia-cypress: "v1.2.3"
+```
+
+### `jahia provision`
+
+Execute a Jahia provisioning script (YAML manifest) against a running Jahia instance. The manifest can be a local file or a public URL — the CLI detects the source automatically.
+
+```bash
+# Provision from a local file
+jahia-cli jahia provision --manifest ./provisioning.yaml
+
+# Provision from a URL
+jahia-cli jahia provision --manifest https://raw.githubusercontent.com/org/repo/main/provisioning.yaml
+
+# Custom target URL and credentials
+jahia-cli jahia provision --manifest ./setup.yaml --url http://jahia.example.com:8080 --username root --password secret
+
+# Attach additional files referenced by the manifest
+jahia-cli jahia provision --manifest ./setup.yaml -f ./settings.properties -f ./license.xml
+
+# Use state to target the active environment
+jahia-cli jahia provision --manifest ./setup.yaml --state
+
+# JSON output for CI/AI
+jahia-cli jahia provision --manifest ./setup.yaml --json
+```
+
+**Flags:**
+- `-m, --manifest` (required) - Path to a local YAML file or a public URL
+
+**Flags:**
+- `--url` - Jahia base URL (default: `http://localhost:8080`)
+- `-u, --username` - Jahia admin username (default: `root`)
+- `-P, --password` - Jahia admin password (default: `root1234`)
+- `-f, --file` - Additional files to attach (repeatable)
+- `-a, --assets` - Directory whose files are attached recursively
+- `--state` - Optional state file path to target the active environment
+- `--json` - Structured JSON output
+
+## AI Agent Usage
+
+All commands support `--json` for structured output. AI agents should:
+
+1. Use `--json` on every command for parseable responses
+2. Check `success` field in JSON output
+3. Use `environment doctor --json` to verify health before running tests
+4. Use `environment logs --component <name> --json` for debugging
 
 ## Development
 
@@ -54,6 +284,7 @@ Say hello from Jahia CLI.
 
 - Node.js >= 20.0.0
 - npm >= 10
+- Docker (for environment commands)
 
 ### Setup
 
@@ -66,69 +297,53 @@ npm install
 ### Run in development
 
 ```bash
-./bin/dev.js hello
-```
-
-### Build
-
-```bash
-npm run build
-```
-
-### Test
-
-```bash
-npm test                # Run tests once
-npm run test:watch      # Run tests in watch mode
-npm run test:coverage   # Run tests with coverage
+./bin/dev.js environment create --component jahia --component pgsql
 ```
 
-### Lint & Format
+### Build & Test
 
 ```bash
-npm run lint        # Check for linting errors
-npm run lint:fix    # Auto-fix linting errors
-npm run format      # Format code with Prettier
+npm run build          # TypeScript compilation + OCLIF manifest
+npm run lint           # ESLint check
+npm test              # Run all tests
+npm run test:coverage  # Tests with coverage
+npm run format         # Prettier formatting
 ```
 
-## Project Structure
+## Architecture
 
 ```
 src/
-└── commands/       # CLI commands (one file per command)
-    └── hello.ts    # Hello world command
-test/
-└── commands/       # Test files mirror src structure
-    └── hello.test.ts
-bin/
-├── dev.js          # Dev entry point (uses tsx)
-└── run.js          # Production entry point
+├── commands/
+│   ├── config/          # Configuration commands (init)
+│   ├── environment/     # Environment lifecycle commands
+│   └── tests/           # Test bootstrap commands (init)
+├── lib/
+│   ├── components/      # Component library (jahia, pgsql, elasticsearch, etc.)
+│   ├── config/          # YAML config parser and defaults
+│   ├── tests/           # Test scaffolding bootstrap helpers
+│   ├── output/          # Dual human/JSON output formatters
+│   ├── providers/       # Provider abstraction (docker, jahiacloudv1 placeholder)
+│   │   └── docker/      # Native Docker CLI integration
+│   └── state/           # Local JSON state persistence
+test/                    # Mirror of src/ with .test.ts files
 ```
 
 ## Contributing
 
 1. Create a feature branch from `main`
-2. Make your changes following the functional programming style
-3. Ensure all tests pass: `npm test`
-4. Ensure linting passes: `npm run lint`
+2. Follow functional programming style (arrow functions, `const`, no mutations)
+3. One function per `.ts` file
+4. Ensure `npm run lint && npm test` passes
 5. Submit a pull request
 
-### Coding Conventions
-
-- **Functional programming**: Use arrow functions, prefer `const`, avoid mutations
-- **TypeScript strict mode**: All types must be explicit, no `any`
-- **Command classes**: OCLIF requires classes for commands, but extract logic into pure functions
-
 ## Releasing
 
 Releases are managed via GitHub Releases:
 
-1. Create a new release on GitHub with a semver tag (e.g., `v1.0.0`)
-2. The release workflow automatically publishes to npm
-
-> **Note:** The repository requires an `NPM_TOKEN` secret for npm publishing.
+1. Create a new release with a semver tag (e.g., `v1.0.0`)
+2. The release workflow automatically publishes to npm and builds a multi-arch Docker image
 
 ## License
 
 [Apache License 2.0](LICENSE)
-A CLI to accelerate developing and testing Jahia in the Agentic era

package/bin/dev.js

@@ -2,4 +2,8 @@
 
 import { execute } from '@oclif/core';
 
-await execute({ development: true, dir: import.meta.url });
+// Use development mode for dev plugins/ts-node, but disable debug
+// to suppress stack traces in error output
+process.env.NODE_ENV = 'development';
+
+await execute({ dir: import.meta.url });

package/dist/commands/config/init.d.ts

@@ -0,0 +1,12 @@
+import { Command } from '@oclif/core';
+export default class ConfigInit extends Command {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        output: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}
+//# sourceMappingURL=init.d.ts.map

package/dist/commands/config/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/commands/config/init.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAS,MAAM,aAAa,CAAC;AAO7C,MAAM,CAAC,OAAO,OAAO,UAAW,SAAQ,OAAO;IAC7C,OAAgB,WAAW,SAEuC;IAElE,OAAgB,QAAQ,WAItB;IAEF,OAAgB,KAAK;;;;MAenB;IAEW,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;CAgElC"}

package/dist/commands/config/init.js

@@ -0,0 +1,76 @@
+import { resolve } from 'node:path';
+import { Command, Flags } from '@oclif/core';
+import { buildBlankConfig } from '../../lib/config/build-blank-config.js';
+import { initializeConfigFile } from '../../lib/config/initialize-config-file.js';
+const DEFAULT_OUTPUT = 'jahia-cli.config.yml';
+export default class ConfigInit extends Command {
+    static description = 'Generate an initialized Jahia CLI configuration file. ' +
+        'Creates a blank scaffold with environment and tests sections.';
+    static examples = [
+        '<%= config.bin %> config init',
+        '<%= config.bin %> config init --output ./my-config.yml',
+        '<%= config.bin %> config init --force --json',
+    ];
+    static flags = {
+        output: Flags.string({
+            char: 'o',
+            description: 'Path to write the configuration YAML file',
+            default: DEFAULT_OUTPUT,
+        }),
+        force: Flags.boolean({
+            char: 'f',
+            description: 'Overwrite output file if it already exists',
+            default: false,
+        }),
+        json: Flags.boolean({
+            description: 'Output result as structured JSON (for AI agents and scripting)',
+            default: false,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(ConfigInit);
+        const outputFile = resolve(flags.output);
+        try {
+            const config = buildBlankConfig();
+            const initialized = await initializeConfigFile({
+                outputFile,
+                config,
+                force: flags.force,
+            });
+            if (!initialized.written) {
+                const message = `Configuration file already exists at "${outputFile}". Use --force to overwrite.`;
+                if (flags.json) {
+                    this.log(JSON.stringify({ success: false, error: 'file_exists', message, outputFile }, null, 2));
+                    this.exit(1);
+                }
+                this.error(message);
+                return;
+            }
+            if (flags.json) {
+                this.log(JSON.stringify({
+                    success: true,
+                    outputFile,
+                }, null, 2));
+            }
+            else {
+                this.log(`✓ Configuration initialized at ${outputFile}`);
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (flags.json) {
+                this.log(JSON.stringify({
+                    success: false,
+                    error: 'config_init_failed',
+                    message,
+                    outputFile,
+                }, null, 2));
+            }
+            else {
+                this.error(message);
+            }
+            this.exit(1);
+        }
+    }
+}
+//# sourceMappingURL=init.js.map

package/dist/commands/config/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../../src/commands/config/init.ts"],"names":[],"mappings":"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"}

package/dist/commands/environment/create.d.ts

@@ -0,0 +1,27 @@
+import { Command } from '@oclif/core';
+import type { ConfigComponent } from '../../lib/config/types.js';
+/**
+ * Prompts the user interactively for Jahia image and builds a minimal config.
+ */
+export declare const promptForJahiaConfig: () => Promise<{
+    readonly image: string;
+}>;
+/**
+ * Prompts the user for optional utility components (e.g., SMTP server).
+ * Returns an array of ConfigComponent entries to add to the environment.
+ */
+export declare const promptForOptionalComponents: () => Promise<readonly ConfigComponent[]>;
+export default class EnvironmentCreate extends Command {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        state: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        config: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'export-config': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+    private resolveConfig;
+}
+//# sourceMappingURL=create.d.ts.map

package/dist/commands/environment/create.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../../src/commands/environment/create.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAS,MAAM,aAAa,CAAC;AAQ7C,OAAO,KAAK,EAAE,eAAe,EAAqB,MAAM,2BAA2B,CAAC;AAYpF;;GAEG;AACH,eAAO,MAAM,oBAAoB,QAAa,OAAO,CAAC;IACpD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB,CAOA,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,2BAA2B,QAAa,OAAO,CAAC,SAAS,eAAe,EAAE,CAYtF,CAAC;AAEF,MAAM,CAAC,OAAO,OAAO,iBAAkB,SAAQ,OAAO;IACpD,OAAgB,WAAW,SAG4C;IAEvE,OAAgB,QAAQ,WAOtB;IAEF,OAAgB,KAAK;;;;;;MAoBnB;IAEW,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;YAwGnB,aAAa;CAyB5B"}