keytec-ai-cli 0.4.0

package/README.md

@@ -0,0 +1,120 @@
+# keytec-ai
+
+One CLI for `.keytec-ai.yml` operations, used by **GitLab CI**, the **DDEV addon**, and the
+`keytec-drupal-deploy` skill — so the logic lives in one tested, versioned place instead of
+being copied into each project.
+
+Komodo registry-deploy model: stacks are declared in git as Komodo Resource Sync TOML
+(`komodo/*.toml`, **one stack per branch**) and created by Komodo; `keytec-ai deployer deploy`
+triggers `DeployStack` for the branch's stack and polls until it completes.
+
+## Run it
+
+Run it with `npx` — a self-contained JS bundle on the public npm registry, no
+install, no `.npmrc`, no auth:
+
+```
+npx keytec-ai-cli config to-env
+npx keytec-ai-cli@0.4.0 deployer deploy develop   # pin a version
+```
+
+In CI, call it the same way (any node image):
+
+```yaml
+# .gitlab-ci.yml in a consumer project
+deploy:
+  image: node:22-alpine
+  script:
+    - npx keytec-ai-cli deployer deploy "$CI_COMMIT_REF_NAME"
+```
+
+For repeated local use, install once: `npm i -g keytec-ai-cli`, then `keytec-ai …`.
+
+## Commands
+
+```
+keytec-ai config to-env [--config <path>] [--to-file <path>]   Export the config as env vars
+keytec-ai deployer deploy [<branch>]            Deploy the branch's Komodo stack
+keytec-ai deployer destroy [<branch>]           Tear down the branch's Komodo stack
+keytec-ai deployer provision-secrets            Create the per-env secret Komodo Variables
+keytec-ai deployer is-deployed --mr <iid>       Is an MR live on its environment?
+keytec-ai deployer release-mrs                  List the MRs a deploy shipped
+```
+
+- `config to-env` renders the whole `.keytec-ai.yml` as flat `UPPER_SNAKE` env vars
+  (nested keys joined with `_`, arrays comma-joined, empty objects skipped). Writes to
+  stdout, or to a file with `--to-file=.env`. The config is located by walking from the
+  current directory up to the filesystem root, so it works from any project subdirectory.
+- `deployer deploy` resolves the branch's stack, ensures its secrets exist, triggers
+  `DeployStack`, and polls until the on-node deploy completes (fails with Komodo logs on
+  error). Stacks are declared in git and created by a Komodo Resource Sync; the CLI never
+  creates stacks or sets image tags.
+
+## Deploy model
+
+Deploy state lives in git as Komodo Resource Sync TOML under `komodo/*.toml` — **not** in
+`.keytec-ai.yml`. Each environment is one `[[stack]]` block keyed by its `branch`; secrets
+are referenced with `[[NAME]]` and provisioned as per-env Komodo Variables.
+
+```toml
+# komodo/stacks.toml
+[[stack]]
+name = "lumora-cms-develop"
+[stack.config]
+branch = "develop"
+environment = """
+DB_PASSWORD=[[LUMORA_DEVELOP_DB_PASSWORD]]
+"""
+```
+
+- one `[[stack]]` per branch — the branch name *is* the environment; 0 or >1 matches errors.
+- `deployer provision-secrets` creates every `[[…]]` secret as a Komodo Variable (idempotent).
+
+## deploy env vars
+
+- deploy / destroy: `KOMODO_URL`, `KOMODO_API_KEY`, `KOMODO_API_SECRET`
+  (+ `CI_COMMIT_REF_NAME` as the default branch in CI).
+- is-deployed / release-mrs: `GITLAB_TOKEN`, `GITLAB_API_URL` (or `CI_API_V4_URL`),
+  `GITLAB_PROJECT_ID` (or `CI_PROJECT_ID`), `CI_COMMIT_SHA`.
+
+## Develop
+
+```
+bun install
+bun test
+bun run dev -- env develop          # run from a dir with .keytec-ai.yml
+bun run build                       # -> ./dist/cli.js (node bundle, what npm publishes)
+```
+
+## Releasing
+
+**Merge to `1.x` = a new version on npm.** Every push to the `1.x` branch runs
+`publish:npm`, which publishes `package.json` `version` to the public npm registry.
+That's the whole release: nothing to tag, no manual publish step.
+
+```
+# 1. work on a feature branch, bump the version, MR into next
+git checkout next && git pull
+git checkout -b feat/my-change
+npm version patch --no-git-tag-version    # bump package.json (patch|minor|major)
+# ... commit, push, open MR, merge into next ...
+
+# 2. release: merge next into 1.x
+git checkout 1.x && git merge next && git push
+# -> CI publishes keytec-ai-cli@<version> to npm
+```
+
+The version is the gate: if `package.json` `version` is already on npm,
+`--tolerate-republish` makes the job a no-op, so pushes to `1.x` without a bump
+publish nothing. **Bump `version` in the MR** for the release to actually ship.
+
+Under the hood `publish:npm` (on `1.x`) runs `prepublishOnly` to bundle `src` into
+`dist/cli.js`, writes an ephemeral `.npmrc` from the masked `NPM_TOKEN` (never
+committed), and runs `bun publish --access public`. `1.x` is a protected branch so
+the protected `NPM_TOKEN` is exposed there.
+
+### CI variables
+
+| Variable | Purpose | Flags |
+|----------|---------|-------|
+| `NPM_TOKEN` | npm automation token for `publish:npm` | masked, protected |