ansensational 0.0.0-stage → 1.2.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/CHANGELOG.md ADDED
@@ -0,0 +1,31 @@
1
+ # Changelog
2
+
3
+ ## 1.1.0
4
+
5
+ ### Added
6
+
7
+ - `ansensational` command (also the default command) with non-interactive flags:
8
+ `--git`, `--pm`, `--force`, and `--yes`.
9
+ - `--json` output for `list` and `search`.
10
+ - Support for GitHub/GitLab tree URLs that point at a subdirectory.
11
+ - Automatic recovery when the local registry is corrupt (the bad file is
12
+ backed up and a clear warning is printed).
13
+ - Sync now preserves locally added templates under `@local`.
14
+ - Release workflow, package metadata, and LICENSE file for npm.
15
+
16
+ ### Fixed
17
+
18
+ - `ansensational` with no arguments now prints help instead of failing with a
19
+ missing argument error.
20
+ - `--version` now reads the version from `package.json`.
21
+ - Invalid templates can no longer corrupt the local registry.
22
+ - Author filters work with both registry usernames and GitHub handles.
23
+ - Package manager switching now removes the correct lockfile and handles
24
+ `bun.lock` as well as `bun.lockb`.
25
+ - Failed clones clean up temporary directories and do not leave partial
26
+ projects behind.
27
+ - Non-interactive runs no longer hang on prompts.
28
+ - Tree/subdirectory template URLs are supported instead of being passed to
29
+ `git clone` unchanged.
30
+ - ANSensationaling into an existing empty directory works; `--force` is required
31
+ for non-empty directories.
package/LICENSE ADDED
@@ -0,0 +1,194 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship made available under
36
+ the License, as indicated by a copyright notice that is included in
37
+ or attached to the work (an example is provided in the Appendix below).
38
+
39
+ "Derivative Works" shall mean any work, whether in Source or Object
40
+ form, that is based on (or derived from) the Work and for which the
41
+ editorial revisions, annotations, elaborations, or other modifications
42
+ represent, as a whole, an original work of authorship. For the purposes
43
+ of this License, Derivative Works shall not include works that remain
44
+ separable from, or merely link (or bind by name) to the interfaces of,
45
+ the Work and Derivative Works thereof.
46
+
47
+ "Contribution" shall mean, as submitted to the Licensor for inclusion
48
+ in the Work by the copyright owner or by an individual or Legal Entity
49
+ authorized to submit on behalf of the copyright owner. For the purposes
50
+ of this definition, "submitted" means any form of electronic, verbal,
51
+ or written communication sent to the Licensor or its representatives,
52
+ including but not limited to communication on electronic mailing lists,
53
+ source code control systems, and issue tracking systems that are managed
54
+ by, or on behalf of, the Licensor for the purpose of discussing and
55
+ improving the Work, but excluding communication that is conspicuously
56
+ marked or designated in writing by the copyright owner as "Not a
57
+ Contribution."
58
+
59
+ "Contributor" shall mean Licensor and any Legal Entity on behalf of
60
+ whom a Contribution has been received by the Licensor and included
61
+ within the Work.
62
+
63
+ 2. Grant of Copyright License. Subject to the terms and conditions of
64
+ this License, each Contributor hereby grants to You a perpetual,
65
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
66
+ copyright license to reproduce, prepare Derivative Works of,
67
+ publicly display, publicly perform, sublicense, and distribute the
68
+ Work and such Derivative Works in Source or Object form.
69
+
70
+ 3. Grant of Patent License. Subject to the terms and conditions of
71
+ this License, each Contributor hereby grants to You a perpetual,
72
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
73
+ (except as stated in this section) patent license to make, have made,
74
+ use, offer to sell, sell, import, and otherwise transfer the Work,
75
+ where such license applies only to those patent claims licensable
76
+ by such Contributor that are necessarily infringed by their
77
+ Contribution(s) alone or by their combined Contributions with the Work.
78
+ If You institute patent litigation against any entity (including a
79
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
80
+ or a Contribution incorporated within the Work constitutes direct
81
+ or contributory patent infringement, then any patent licenses
82
+ granted to You under this License for that Work shall terminate
83
+ as of the date such litigation is filed.
84
+
85
+ 4. Redistribution. You may reproduce and distribute copies of the
86
+ Work or Derivative Works thereof in any medium, with or without
87
+ modifications, and in Source or Object form, provided that You
88
+ meet the following conditions:
89
+
90
+ (a) You must give any other recipients of the Work or Derivative
91
+ Works a copy of this License; and
92
+
93
+ (b) You must cause any modified files to carry prominent notices
94
+ stating that You changed the files; and
95
+
96
+ (c) You must retain, in the Source form of any Derivative Works
97
+ that You distribute, all copyright, patent, trademark, and
98
+ attribution notices from the Source form of the Work,
99
+ excluding those notices that do not pertain to any part of
100
+ the Derivative Works; and
101
+
102
+ (d) If the Work includes a "NOTICE" text file as part of its
103
+ distribution, You must include a readable copy of the
104
+ attribution notices contained within such NOTICE file, in
105
+ at least one of the following places: within a NOTICE text
106
+ file distributed as part of the Derivative Works; within
107
+ the Source form or documentation, if provided along with the
108
+ Derivative Works; or, within a display generated by the
109
+ Derivative Works, if and wherever such third-party notices
110
+ normally appear. The contents of the NOTICE file are for
111
+ informational purposes only and do not modify the License.
112
+ You may add Your own attribution notices within Derivative
113
+ Works that You distribute, alongside or as an addendum to
114
+ the NOTICE text from the Work, provided that such additional
115
+ attribution notices cannot be construed as modifying the License.
116
+
117
+ You may add Your own license statement for Your modifications and
118
+ may provide additional grant of rights to use, copy, modify, merge,
119
+ publish, distribute, sublicense, and/or sell copies of Your modifications,
120
+ and to permit persons to whom Your modifications are furnished to do
121
+ so, provided that such rights are in addition to the rights granted
122
+ above.
123
+
124
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
125
+ any Contribution intentionally submitted for inclusion in the Work
126
+ by You to the Licensor shall be under the terms and conditions of
127
+ this License, without any additional terms or conditions.
128
+ Notwithstanding the above, nothing herein shall supersede or modify
129
+ the terms of any separate license agreement you may have executed
130
+ with Licensor regarding such Contributions.
131
+
132
+ 6. Trademarks. This License does not grant permission to use the trade
133
+ names, trademarks, service marks, or product names of the Licensor,
134
+ except as required for reasonable and customary use in describing the
135
+ origin of the Work and reproducing the content of the NOTICE file.
136
+
137
+ 7. Disclaimer of Warranty. Unless required by applicable law or
138
+ agreed to in writing, Licensor provides the Work (and each
139
+ Contributor provides its Contributions) on an "AS IS" BASIS,
140
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
141
+ implied, including, without limitation, any warranties or conditions
142
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
143
+ PARTICULAR PURPOSE. You are solely responsible for determining the
144
+ appropriateness of using or reproducing the Work and assume any
145
+ risks associated with Your exercise of permissions under this License.
146
+
147
+ 8. Limitation of Liability. In no event and under no legal theory,
148
+ whether in tort (including negligence), contract, or otherwise,
149
+ unless required by applicable law (such as deliberate and grossly
150
+ negligent acts) or agreed to in writing, shall any Contributor be
151
+ liable to You for damages, including any direct, indirect, special,
152
+ incidental, or exemplary damages of any character arising as a
153
+ result of this License or out of the use or inability to use the
154
+ Work (including but not limited to damages for loss of goodwill,
155
+ work stoppage, computer failure or malfunction, or all other
156
+ commercial damages or losses), even if such Contributor has been
157
+ advised of the possibility of such damages.
158
+
159
+ 9. Accepting Warranty or Liability. While redistributing the Work or
160
+ Derivative Works thereof, You may choose to offer, and charge a fee
161
+ for, acceptance of support, warranty, indemnity, or other liability
162
+ obligations and/or rights consistent with this License. However, in
163
+ accepting such obligations, You may offer such obligations only on
164
+ Your own behalf and on Your sole responsibility, not on behalf of
165
+ any other Contributor, and only if You agree to indemnify, defend,
166
+ and hold each Contributor harmless for any liability incurred by,
167
+ or claims asserted against, such Contributor by reason of your
168
+ accepting any warranty or additional liability.
169
+
170
+ END OF TERMS AND CONDITIONS
171
+
172
+ APPENDIX: How to apply the Apache License to your work.
173
+
174
+ To apply the Apache License to your work, attach the following
175
+ boilerplate notice, with the fields enclosed by brackets "[]"
176
+ replaced with your own identifying information. (Don't include
177
+ the brackets!) The text should be enclosed in the appropriate
178
+ comment syntax for the format in question. It may also be
179
+ distributed in a "work representing file" form as described in
180
+ Section 4 d of the Apache License, Version 2.0.
181
+
182
+ Copyright 2024 Andi Nugroho
183
+
184
+ Licensed under the Apache License, Version 2.0 (the "License");
185
+ you may not use this file except in compliance with the License.
186
+ You may obtain a copy of the License at
187
+
188
+ http://www.apache.org/licenses/LICENSE-2.0
189
+
190
+ Unless required by applicable law or agreed to in writing, software
191
+ distributed under the License is distributed on an "AS IS" BASIS,
192
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
193
+ See the License for the specific language governing permissions and
194
+ limitations under the License.
package/README.md CHANGED
@@ -1,3 +1,215 @@
1
- # Temporary Holding Version
1
+ # Ansensational CLI
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![npm version](https://img.shields.io/npm/v/ansensational.svg)](https://www.npmjs.com/package/ansensational)
4
+ [![npm downloads](https://img.shields.io/npm/dm/ansensational.svg)](https://www.npmjs.com/package/ansensational)
5
+ [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
6
+ [![Node.js](https://img.shields.io/node/v/ansensational.svg)](https://nodejs.org/)
7
+
8
+ **ANSensational new projects from GitHub or GitLab templates with a single command.**
9
+
10
+ Ansensational is a community-driven template registry and CLI. Discover a
11
+ template, clone it into a clean project, choose how git and your package
12
+ manager should be handled, and start building.
13
+
14
+ ## Features
15
+
16
+ - **One-command ansensationaling** — `ansensational @author/template my-app`
17
+ - **GitHub, GitLab, and custom Git hosts** — including URLs that point at a
18
+ branch or subdirectory.
19
+ - **Clean starts** — keep the original history, create a fresh repository, or
20
+ remove git entirely.
21
+ - **Package manager aware** — detects npm, pnpm, yarn, and bun, and can switch
22
+ the template to your preferred manager.
23
+ - **Community registry** — search and list curated templates, with a local
24
+ cache for offline use.
25
+ - **Private/local templates** — add your own templates under `@local` and keep
26
+ them across registry syncs.
27
+ - **Scriptable** — `--json` output, non-interactive flags, and no prompts in CI.
28
+
29
+ ## Installation
30
+
31
+ ```bash
32
+ # npm
33
+ npm install -g ansensational
34
+
35
+ # pnpm
36
+ pnpm add -g ansensational
37
+
38
+ # yarn
39
+ yarn global add ansensational
40
+
41
+ # bun
42
+ bun add -g ansensational
43
+ ```
44
+
45
+ Requires Node.js 18 or newer. No installation is required to try it:
46
+
47
+ ```bash
48
+ npx ansensational list --remote
49
+ ```
50
+
51
+ ## Quick start
52
+
53
+ ```bash
54
+ # Refresh the community registry (optional; commands can fetch remotely)
55
+ ansensational sync
56
+
57
+ # Browse templates
58
+ ansensational list --remote
59
+
60
+ # ANSensational one
61
+ ansensational @andi-nugroho/nest-backend my-app
62
+ ```
63
+
64
+ ## Commands
65
+
66
+ | Command | Description |
67
+ | --------------------------------------- | ----------------------------------------------- |
68
+ | `ansensational <slug> [dest]` | ANSensational a template (default command) |
69
+ | `ansensational ansensational <slug> [dest]` | Explicit form of the same command |
70
+ | `ansensational list` | List templates in the local cache |
71
+ | `ansensational search <query>` | Search local and remote templates |
72
+ | `ansensational sync` | Download the latest community registry |
73
+ | `ansensational add <slug> <url>` | Add or update a template in your local registry |
74
+
75
+ Templates can be referenced as `@author/slug`, `author/slug`, or a bare `slug`
76
+ when the slug is unique.
77
+
78
+ ### ANSensational options
79
+
80
+ | Option | Description |
81
+ | ---------------------- | ------------------------------------------------------------ |
82
+ | `-g, --git <strategy>` | `keep` original history, `fresh` repository, or `remove` git |
83
+ | `-p, --pm <manager>` | `npm`, `pnpm`, `yarn`, or `bun` |
84
+ | `-f, --force` | Allow writing into a non-empty destination |
85
+ | `-y, --yes` | Skip prompts and use defaults |
86
+
87
+ ```bash
88
+ # Non-interactive setup for CI or scripts
89
+ ansensational @andi-nugroho/backend my-api --git fresh --pm pnpm --yes
90
+
91
+ # ANSensational into the current (empty) directory
92
+ ansensational @andi-nugroho/webapp .
93
+
94
+ # Add files to an existing directory (explicit opt-in)
95
+ ansensational @andi-nugroho/webapp ./existing --force
96
+ ```
97
+
98
+ Without `--git`, the CLI prompts when running in a terminal and uses `fresh`
99
+ when it is not interactive.
100
+
101
+ ### List and search
102
+
103
+ ```bash
104
+ # Local cache only
105
+ ansensational list
106
+
107
+ # Include the remote registry
108
+ ansensational list --remote
109
+
110
+ # Filter by type, framework, or author
111
+ ansensational list --type backend --framework nestjs
112
+ ansensational list --author andi-nugroho
113
+ ansensational list --author @andi-nugroho
114
+
115
+ # Search names, descriptions, tags, features, and authors
116
+ ansensational search postgres
117
+ ansensational search nextjs --type fullstack
118
+
119
+ # Machine-readable output
120
+ ansensational list --remote --json
121
+ ansensational search hono --json
122
+ ```
123
+
124
+ `--author` accepts both the registry username (for example `andi-nugroho`) and
125
+ the author's GitHub handle (for example `andi-nugroho`).
126
+
127
+ ### Add a local template
128
+
129
+ ```bash
130
+ ansensational add my-private-kit https://github.com/me/private-kit \
131
+ --type fullstack \
132
+ --framework nextjs \
133
+ --description "Internal starter" \
134
+ --tags "typescript,auth,drizzle" \
135
+ --features "rbac,data-tables"
136
+
137
+ # Local templates are stored under @local
138
+ ansensational @local/my-private-kit ./my-app
139
+ ```
140
+
141
+ Local templates survive `ansensational sync`. Invalid slugs, URLs, types, and
142
+ frameworks are rejected before anything is written, so a typo cannot corrupt
143
+ your registry.
144
+
145
+ ### Sync
146
+
147
+ ```bash
148
+ ansensational sync
149
+ ```
150
+
151
+ Sync replaces the cached community templates with the latest remote registry
152
+ and preserves templates you added under `@local`. If the local registry file
153
+ is ever corrupt, Ansensational backs it up and starts from a clean registry
154
+ instead of crashing.
155
+
156
+ ## Template URL formats
157
+
158
+ ```text
159
+ https://github.com/owner/repo
160
+ https://github.com/owner/repo/tree/main
161
+ https://github.com/owner/repo/tree/main/apps/web
162
+ https://gitlab.com/group/subgroup/repo
163
+ https://gitlab.com/group/subgroup/repo/-/tree/main/packages/app
164
+ ```
165
+
166
+ `git@github.com:owner/repo.git` and `ssh://git@github.com/owner/repo.git` are
167
+ accepted by `add` and normalised to HTTPS. `file://` URLs are supported for
168
+ local testing and private offline repositories.
169
+
170
+ ## Environment variables
171
+
172
+ | Variable | Purpose |
173
+ | --------------------------------- | --------------------------------------------------------------- |
174
+ | `ANSENSATIONAL_HOME` | Override the local data directory (default `~/.ansensational`) |
175
+ | `ANSENSATIONAL_REGISTRY_URL` | Use a custom registry JSON URL |
176
+ | `ANSENSATIONAL_REGISTRY_TIMEOUT` | Registry request timeout in milliseconds (default `15000`) |
177
+ | `ANSENSATIONAL_DEBUG` | Print stack traces for unexpected errors |
178
+
179
+ ## Troubleshooting
180
+
181
+ **The registry is empty.** Run `ansensational sync` or use
182
+ `ansensational list --remote`.
183
+
184
+ **A template is not found.** Run `ansensational search <query>` or use the full
185
+ `@author/slug` form. Use `ansensational list --remote -a <author>` to list an
186
+ author's templates.
187
+
188
+ **Cloning fails with an authentication error.** The template repository is
189
+ private or has been moved. Make sure your local git credentials can clone the
190
+ URL directly.
191
+
192
+ **The local registry was invalid.** Ansensational prints the backup path and
193
+ starts with an empty registry. Running `ansensational sync` restores the community
194
+ templates.
195
+
196
+ **Prompts are skipped.** Prompts only run in an interactive terminal. Use
197
+ `--git` and `--pm` to set values explicitly in CI.
198
+
199
+ ## Contributing templates
200
+
201
+ The community registry lives in
202
+ [`content/templates`](https://github.com/andi-nugroho/ansensational/tree/main/content/templates).
203
+ Add your template's JSON file and open a pull request. See the
204
+ [template contribution guide](https://github.com/andi-nugroho/ansensational/blob/main/content/templates/CONTRIBUTING.md).
205
+
206
+ ## Links
207
+
208
+ - [Website and template directory](https://ansensational.vercel.app)
209
+ - [Source code](https://github.com/andi-nugroho/ansensational)
210
+ - [Issues](https://github.com/andi-nugroho/ansensational/issues)
211
+ - [Changelog](./CHANGELOG.md)
212
+
213
+ ## License
214
+
215
+ MIT © ANSensational Contributors
@@ -0,0 +1 @@
1
+ #!/usr/bin/env node