@deessejs/cli 2.2.0 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,27 +1,29 @@
1
1
  # @deessejs/cli
2
2
 
3
- CLI for the DeesseJS template registry.
3
+ CLI for the DeesseJS template registry and block sources.
4
4
 
5
- ## Install (V1)
5
+ ## Install
6
+
7
+ The package is published as `@deessejs/cli` and exposes the `deessejs` executable:
6
8
 
7
9
  ```bash
8
- npx deessejs@latest <command>
10
+ npx @deessejs/cli@latest <command>
9
11
  ```
10
12
 
11
- Other release channels (ADR-021):
12
-
13
- - `@canary` — on-demand pre-release of the current `staging` branch. Published by the `release.yml` workflow via `workflow_dispatch` with the `canary` input. `npx deessejs@canary <command>`.
14
- - Per-PR previews — every PR gets a SHA-keyed ephemeral preview via [pkg.pr.new](https://pkg.pr.new). The install URL is posted as a sticky comment on the PR by the `cli-preview.yml` workflow.
13
+ Other release channels:
15
14
 
16
- Future (V1.1+, when pro templates need auth): `npm i -g @deessejs/cli`.
15
+ - `@canary`: on-demand pre-release of the current `staging` branch. Published by the `release.yml` workflow via `workflow_dispatch` with the `canary` input. Install with `npx @deessejs/cli@canary <command>`.
16
+ - Per-PR previews: every PR gets a SHA-keyed ephemeral preview via [pkg.pr.new](https://pkg.pr.new). The install URL is posted as a sticky comment on the PR by the `cli-preview.yml` workflow.
17
17
 
18
18
  ## Commands
19
19
 
20
- | Command | Role |
21
- |---|---|
22
- | `deessejs init <slug>` | Clone a template repo + install dependencies |
23
- | `deessejs list` | List available templates |
24
- | `deessejs info <slug>` | Show details for one template |
20
+ | Command | Role |
21
+ | ------------------------------------ | --------------------------------------------------------------- |
22
+ | `deessejs init <slug-or-github-url>` | Create a project from a catalog template or a GitHub repository |
23
+ | `deessejs list` | List available templates |
24
+ | `deessejs info <slug-or-github-url>` | Show validated descriptor details for a template |
25
+ | `deessejs block info <source>` | Show a validated block descriptor summary |
26
+ | `deessejs block check [source]` | Validate a block descriptor and its referenced assets |
25
27
 
26
28
  ## Examples
27
29
 
@@ -29,15 +31,37 @@ Future (V1.1+, when pro templates need auth): `npm i -g @deessejs/cli`.
29
31
  deessejs list
30
32
  deessejs list --category saas --json
31
33
  deessejs info saas-starter --json
34
+ deessejs info https://github.com/owner/repository --ref main
35
+ deessejs block info ./blocks/upstash-redis
36
+ deessejs block info https://github.com/deessejs/blocks/tree/main/upstash-redis --json
37
+ deessejs block check ./blocks/upstash-redis
38
+ deessejs block check https://github.com/deessejs/blocks/upstash-redis --json
32
39
  deessejs init saas-starter
33
40
  deessejs init saas-starter --ref develop --no-install
41
+ deessejs init https://github.com/owner/repository
42
+ deessejs init saas-starter --verbose
34
43
  ```
35
44
 
45
+ `init` accepts a catalog slug or an HTTPS URL to a GitHub repository root. Both forms use the repository's root `deesse-template.json` to select the files to create. The descriptor must be present and valid; there is no Git clone fallback. `--ref` selects a branch or other Git ref. `--force` allows an existing empty target directory; it never removes existing files.
46
+
47
+ `info` accepts a catalog slug or GitHub repository URL and shows the same descriptor fields for both. Slugs are mapped to repositories through a lightweight catalog lookup; `info` does not fetch the GitHub-enriched listing. It then reads only the root `deesse-template.json` through GitHub's Contents API, without downloading or inventorying the full repository. `--ref` inspects a specific branch or other Git ref. With `--json`, the result contains the validated `descriptor` and source repository.
48
+
49
+ `block info` accepts a local block directory, a public HTTPS GitHub repository URL, a shorthand GitHub directory URL such as `https://github.com/owner/repository/block`, or a canonical `/tree/<ref>/<block-path>` URL. It resolves a remote ref to a commit before reading the root `deesse-block.json` and the package manifests declared by its file mappings. It does not modify a project, install dependencies or execute package scripts. `--json` returns the descriptor, package summaries and source identity.
50
+
51
+ `block check` accepts the same local and GitHub sources and defaults to the current directory when no source is given. It validates the descriptor and reads every file declared in `install.files`, including package manifests. It reports all unreadable assets without writing to the project, installing dependencies or executing package scripts. It does not yet plan changes against a receiving project. Use `--json` for stable diagnostic codes and source paths.
52
+
53
+ By default, `init` hides package manager logs and shows a concise progress summary. Pass `--verbose` to print the resolved template source, ref, destination, commit, and selected file count, as well as the full package manager output when installation runs. Verbose details go to stderr so `--json` keeps stdout machine-readable. The details are also shown with `--no-install`.
54
+
36
55
  ## Global flags
37
56
 
38
- - `--api-url <url>` — override the templates endpoint (default: `https://deessejs.com/api/templates`)
39
- - `--json` — JSON output for scripting
57
+ - `--api-url <url>`: override the templates endpoint (default: `https://deessejs.com/api/templates`)
58
+ - `--json`: JSON output for scripting
40
59
 
41
60
  ## License
42
61
 
43
- UNLICENSED for V1 (private). License TBD before npm publish.
62
+ MIT.
63
+
64
+ ## Related
65
+
66
+ - **Uses**: [`@workspace/api`](https://github.com/deessejs/deessejs/blob/staging/packages/api/README.md), [`@workspace/contracts`](https://github.com/deessejs/deessejs/blob/staging/packages/contracts/README.md)
67
+ - **Bundles**: the workspace dependencies into the published package at build time, so nothing is resolved at run time