@deessejs/cli 2.2.0 → 3.0.0-canary.20261103073430.3e4dd45

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,34 @@
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
+ Requires Node.js 22.14 or later.
6
+
7
+ ## Install
8
+
9
+ The package is published as `@deessejs/cli` and exposes the `deessejs` executable:
6
10
 
7
11
  ```bash
8
- npx deessejs@latest <command>
12
+ npx @deessejs/cli@latest <command>
9
13
  ```
10
14
 
11
- Other release channels (ADR-021):
15
+ Other release channels:
12
16
 
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.
15
-
16
- Future (V1.1+, when pro templates need auth): `npm i -g @deessejs/cli`.
17
+ - `@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>`.
18
+ - 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
19
 
18
20
  ## Commands
19
21
 
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 |
22
+ | Command | Role |
23
+ | ------------------------------------- | --------------------------------------------------------------- |
24
+ | `deessejs init <slug-or-github-url>` | Create a project from a catalog template or a GitHub repository |
25
+ | `deessejs list` | List available templates |
26
+ | `deessejs info <slug-or-github-url>` | Show validated descriptor details for a template |
27
+ | `deessejs block info <source>` | Show a validated block descriptor summary |
28
+ | `deessejs block check [source]` | Validate a block descriptor and its referenced assets |
29
+ | `deessejs organization list` | List organizations the signed-in user belongs to |
30
+ | `deessejs organization info <slug>` | Show one of the signed-in user's organizations |
31
+ | `deessejs organization create <name>` | Create an organization |
25
32
 
26
33
  ## Examples
27
34
 
@@ -29,15 +36,51 @@ Future (V1.1+, when pro templates need auth): `npm i -g @deessejs/cli`.
29
36
  deessejs list
30
37
  deessejs list --category saas --json
31
38
  deessejs info saas-starter --json
39
+ deessejs info https://github.com/owner/repository --ref main
40
+ deessejs block info ./blocks/upstash-redis
41
+ deessejs block info https://github.com/deessejs/blocks/tree/main/upstash-redis --json
42
+ deessejs block check ./blocks/upstash-redis
43
+ deessejs block check https://github.com/deessejs/blocks/upstash-redis --json
32
44
  deessejs init saas-starter
33
45
  deessejs init saas-starter --ref develop --no-install
46
+ deessejs init https://github.com/owner/repository
47
+ deessejs init saas-starter --verbose
48
+ deessejs auth login
49
+ deessejs organization list
50
+ deessejs organization info acme
51
+ deessejs organization create "Acme Studio"
52
+ deessejs organization list --json
53
+ deessejs organization template list acme --json
54
+ deessejs organization template info acme starter-kit
55
+ deessejs organization template add acme --slug starter-kit --name "Starter Kit" --repository https://github.com/acme/starter-kit --category saas
34
56
  ```
35
57
 
58
+ `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.
59
+
60
+ If the selected files include a root `deesse.json`, `init` validates it against project config V1 and preserves its contents. If the template does not include one, `init` creates a default config with the project schema URL and `formatVersion: 1`.
61
+
62
+ `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.
63
+
64
+ `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.
65
+
66
+ `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.
67
+
68
+ Organization commands require an active session from `deessejs auth login`. `list` and `info` use Better Auth's authenticated organization endpoints and only show organizations the caller belongs to. `create` proposes a slug from the name, then sends the name and slug through DeesseJS's authenticated provisioning API. The server validates the slug, resolves collisions and returns the stored slug. Creating an organization does not change the active organization. Each command accepts `--json` for scripting.
69
+
70
+ `organization template list <organization-slug>` lists all templates owned by that organization that the signed-in user can access, including templates that have not been submitted for publication. `info <organization-slug> <template-slug>` shows one owned template. Both expose review and publication state independently from organization ownership. `add <organization-slug>` requires `--slug`, `--name`, `--repository` and `--category`; optional metadata uses `--description`, repeatable `--label` (repeat the option for each label) and `--license`. The API validates the public GitHub repository and requires an organization owner or admin. Adding a template creates an organization-owned entry; it does not publish it. Use `--json` for scripting.
71
+
72
+ 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`.
73
+
36
74
  ## Global flags
37
75
 
38
- - `--api-url <url>` — override the templates endpoint (default: `https://deessejs.com/api/templates`)
39
- - `--json` — JSON output for scripting
76
+ - `--api-url <url>`: override the templates endpoint (default: `https://deessejs.com/api/templates`)
77
+ - `--json`: JSON output for scripting
40
78
 
41
79
  ## License
42
80
 
43
- UNLICENSED for V1 (private). License TBD before npm publish.
81
+ MIT.
82
+
83
+ ## Related
84
+
85
+ - **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)
86
+ - **Bundles**: the workspace dependencies into the published package at build time, so nothing is resolved at run time