inferative 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,70 @@
+Copyright (c) 2024 WP Online Magyarország Kft.
+Website: https://wpo.hu
+All Rights Reserved.
+
+==============================================================================
+WP Online Magyarország Kft. - Internal Use Software License
+==============================================================================
+
+This software package and its accompanying documentation (collectively, "the Software")
+are the proprietary and confidential information of WP Online Magyarország Kft.
+("the Company").
+
+1.  GRANT OF LICENSE:
+    Subject to the terms and conditions of this License, the Company grants to
+    its employees and authorized contractors ("Authorized Users") a non-exclusive,
+    non-transferable, revocable license to install, use, copy, and modify the
+    Software solely for internal Company business purposes.
+
+2.  RESTRICTIONS:
+    Authorized Users shall not:
+    a.  Distribute, sublicense, sell, rent, lease, lend, or otherwise transfer
+        the Software, or any part thereof, to any third party outside of
+        WP Online Magyarország Kft. without the express prior written permission
+        of an authorized representative of the Company.
+    b.  Use the Software for any purpose not expressly permitted by this License,
+        including any personal or commercial projects unrelated to the
+        Company's business.
+    c.  Remove or alter any copyright, trademark, or other proprietary notices
+        contained in the Software.
+    d.  Reverse engineer, decompile, or disassemble the Software, except and
+        only to the extent that such activity is expressly permitted by
+        applicable law notwithstanding this limitation.
+
+3.  OWNERSHIP AND INTELLECTUAL PROPERTY:
+    The Company retains all right, title, and interest in and to the Software,
+    including all copyrights, patents, trade secrets, trademarks, and other
+    intellectual property rights therein. No rights are granted to Authorized
+    Users other than those expressly set forth in this License.
+
+4.  CONFIDENTIALITY:
+    The Software, including its source code, design, and structure, is
+    confidential information of the Company. Authorized Users shall treat the
+    Software with the same degree of care as they treat other Company
+    confidential information and shall not disclose it to any third party
+    without the Company's prior written consent.
+
+5.  NO WARRANTY:
+    THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL
+    THE COMPANY BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER
+    IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN
+    CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+6.  TERMINATION:
+    This License will terminate automatically if an Authorized User breaches any
+    of its terms and conditions. The license granted herein is also contingent
+    upon continued employment or contract with the Company and terminates
+    immediately upon the cessation of that relationship. Upon termination, the
+    Authorized User must cease all use of the Software and destroy all copies
+
+    of the Software in their possession or control.
+
+7.  GOVERNING LAW:
+    This License shall be governed by and construed in accordance with the laws
+    of Hungary, without regard to its conflict of law principles. Any disputes
+    arising under or in connection with this License shall be subject to the
+        exclusive jurisdiction of the courts of Hungary.
+
+For questions regarding this license, please contact office@wpo.hu.

package/README.md

@@ -1,3 +1,98 @@
-# inferative
+# `inferative`
 
-This package name is reserved. The package has no content yet.
+The Inferative command line. It is on public npm, ships built JavaScript and runs under plain `node` (version 24 or
+later). It has the command `init`, which creates a project, and the group `site`: the commands a website runs against
+its channel.
+
+```sh
+npx inferative init my-site
+npx inferative site --help
+```
+
+## What a site needs first
+
+The command line itself comes from public npm. Its dependencies, the `@inferative/*` packages and the `@heximon/*`
+packages they use, come from GitHub Packages. So `npx inferative` works in a folder where npm can read both scopes:
+
+```ini
+@inferative:registry=https://npm.pkg.github.com
+@heximon:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=<a GitHub token with the read:packages scope>
+```
+
+`inferative site doctor` checks both scopes and the token, reads one package through each scope, and prints the
+lines to add for the first scope that fails.
+
+## `inferative init`
+
+`inferative init [directory]` creates a project from a starter. `npm create inferative` runs the same command (see
+[`create-inferative`](../create-inferative)).
+
+```sh
+npx inferative init my-site
+```
+
+| Argument or flag | What it does |
+| :-- | :-- |
+| `directory` | The folder to create. When you leave it out, the current folder is the target. |
+| `--starter <name>` | The starter to use. `nuxt-cloudflare` by default. |
+| `--source <giget source>` | Download this giget source alone, instead of the default sources. |
+| `--local <folder>` | Copy `<folder>/<starter>` instead of a download. For tests and for work on the starters. |
+| `--no-install` | Do not run `pnpm install`. |
+| `--cwd <folder>` | The folder in which a named `directory` is created. The current folder by default. |
+
+The target folder must not exist, or must be empty. The command never overwrites a file. The package name is the
+base name of the folder. A named folder must have a valid npm name: lowercase letters, digits, and `.` `_` `-`. The
+current folder keeps its name on disk, so the command changes the name to a valid one (`My Site` becomes `my-site`).
+
+The command does these steps in this order:
+
+1. It writes `@inferative:registry=https://npm.pkg.github.com` and `@heximon:registry=https://npm.pkg.github.com`
+   into the `.npmrc` of the project. It adds only the lines that are missing. It never removes a line and never writes
+   a token.
+2. It probes both scopes, as `inferative site doctor` does. If a scope fails, the command removes what it wrote, prints
+   the lines to add to your `~/.npmrc`, and exits with code 1. It downloads nothing. The probe runs `npm` through
+   [tinyexec](https://github.com/tinylibs/tinyexec) with `--prefix <the new folder>`, so npm reads the `.npmrc` of the
+   new project and not one of a project above it. On Windows tinyexec escapes each argument, so a folder name with a
+   space or an `&` reaches npm as one argument.
+3. It downloads the starter from the repository `inferative/starters`, with giget. The command tries
+   `gh:inferative/starters/<starter>#v<major.minor>` first, where `major.minor` is the version of this command line.
+   If that download fails, it tries `gh:inferative/starters/<starter>#main`. A `--source` is tried alone. Only a failed
+   download moves on to the next source.
+4. It sets `name` in `package.json`, and sets the range of `inferative` and of every `@inferative/*` dependency to
+   `^<version of this command line>`. The other ranges stay as the starter pins them.
+5. It runs `pnpm install` in the project, through [nypm](https://github.com/unjs/nypm). nypm runs pnpm through
+   Corepack when Corepack is installed, and runs `pnpm` directly when it is not. If pnpm is missing, or the install
+   fails, the command exits with code 1 and keeps the project, because the files are complete.
+
+At the end, the command prints the next steps: `cd` into the folder, copy `.env.example` to `.env`, run `pnpm db:generate` once, and run `pnpm dev`.
+
+## The `site` commands
+
+Run them from the site's folder. The command finds the site root: the nearest folder above the working directory
+with a `package.json`. It loads the site's declarations from `shared/site.ts` there, through `jiti`, because that
+file is the site's own TypeScript. `--site <path>` names another declarations module.
+
+| Command | What it does |
+| :-- | :-- |
+| `inferative site check` | Audits the declarations against the components, builds the manifest and measures it. Needs no network and no credential. `--against <api>` also reports whether the channel serves this build. |
+| `inferative site sync` | Publishes the manifest to the channel, then waits until the channel serves that version. `--first-sync` publishes the first-sync catalog. `--manifest <file>` publishes a prebuilt envelope as it is. |
+| `inferative site doctor [origin]` | Reports registry access, then reads the diagnostic of a running site at `<origin>/_site/health`. `--local` diagnoses from the site's configuration instead. `--path <path>` names a diagnostic mounted elsewhere. |
+| `inferative site config` | Prints what the command line read from the declarations and the runtime configuration. |
+
+`sync` presents the key in `INFERATIVE_MANIFEST_TOKEN`. The channel and the API come from the `site` runtime config
+section, or from the `INFERATIVE_SITE_*` variables. Every `site` command first reads the `.env` file of the site root,
+the file the connect guide of the dashboard fills. A variable that is already set in the environment wins over the
+file, and a missing file is not an error. The agent skill (`docs/skills/inferative`, the page
+`site-deploy-and-topologies`) lists every variable and every exit code.
+
+## How it is built
+
+`vp pack` bundles `src/bin.ts` into `dist/bin.mjs`, and `src/index.ts` into `dist/index.mjs`. The index is the library
+entry: it exports `InitCommand`, which `create-inferative` runs. The pack bundles the `@inferative/*` subpaths that
+map to raw TypeScript (`core`, `utils`), because Node cannot load those from `node_modules`. Every other
+`@inferative/*` and `@heximon/*` import stays external and appears in `dependencies`. That way the command line and the site it reads
+share one copy of each `./api` and `./config` module. `deps.onlyImport` in `vite.config.ts` fails the build when the
+output imports a package that `dependencies` does not name.
+
+The package has no `jiti` loader for its own code. `jiti` reads only the site's declarations file.

package/dist/bin.d.mts

@@ -0,0 +1 @@
+export {}