@catladder/cli 0.0.0-main-8dbb6c76 → 0.0.0-main-a6b45abe

package/dist/bundles/skills/catladder-pipelines/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: catladder-pipelines
+description: Understanding and debugging the CI/CD pipelines catladder generates (GitLab CI and GitHub Actions) — pipeline triggers, stages, environments, caching, job images, releases, and infrastructure drift. Use when investigating failing CI jobs, when asked why/when a job runs, when changing caching or job behavior, or when deployments misbehave. Triggers on "pipeline", "CI job", "gitlab-ci", "workflow", "deploy failed", "cache", "release".
+---
+
+# How catladder pipelines work
+
+All pipeline files are generated from `catladder.ts` — fix pipeline
+problems in the config (see `catladder-config` skill), never in the
+generated YAML.
+
+## Triggers and environments
+
+| Trigger | Runs on | Deploys to |
+|---|---|---|
+| `mainBranch` | push to the main branch | `dev` |
+| `mr` | merge/pull requests | `review` (one app per MR/PR) |
+| `taggedRelease` | git tags | `stage`, `prod` |
+
+Generated layout:
+
+- **GitLab**: `.gitlab-ci.yml` includes generated files from
+  `.catladder-generated/gitlab/` (one per trigger).
+- **GitHub**: workflows in `.github/workflows/` (generated ones carry a
+  "generated by catladder" header; others are unmanaged). Manual
+  actions are per-kind `workflow_dispatch` workflows, visually grouped
+  by their emoji prefix in the Actions sidebar: `🚀 catladder create
+  release`, `▶️ catladder deploy` (manual-gated deploys), `🛑 catladder
+  stop`, `↩️ catladder rollback` — when all of a kind's tasks target one
+  env the name carries it (e.g. `▶️ catladder deploy prod`); otherwise
+  pick the task from the workflow's dropdown. Review apps are stopped
+  automatically when their pull request closes (`🛑 catladder stop
+  review app`); the same workflow can be dispatched with a PR number to
+  tear one down while the pull request is still open (gitlab runs these as manual jobs inside the pipeline
+  instead).
+
+Stages: setup → test → build → deploy → verify (post-deploy checks),
+plus stop jobs for review-app teardown.
+
+## Job images and catci
+
+Jobs run in catladder-provided images (`🐳 catladder image <name>` build
+jobs). Their definitions are materialized into
+`.catladder-generated/images/` and built in the project's own registry
+under `catladder/` (content-hashed, rebuilt only on change).
+`.catladder-generated/catci/` holds a small bundled CI companion used by
+generated jobs (e.g. the release security audit) — all generated, never
+edit.
+
+Projects can declare their own job images under `images` in
+`catladder.ts` (`🐳 image <name>` build jobs, pushed to `job-images/` in
+the registry) and reference them in any `jobImage` field via
+`{ image: "<name>" }` — see the `catladder-builds` skill. A declared
+Dockerfile directory is used in place; an inline `dockerfile` is
+materialized into `.catladder-generated/images/project/<name>/`. Either
+way the build job is skipped when the content hash already exists in
+the registry.
+
+## Caching
+
+Cache configuration is generated per build type. **yarn** node builds
+cache `node_modules` and the `.yarn` zip cache; GitLab uses mutable
+caches with fallback keys (review branches fall back to the dev cache),
+GitHub immutable lockfile-keyed caches where only the build job writes.
+**pnpm** builds cache nothing: measured on a 3800-package monorepo,
+moving the store or node_modules through a CI cache costs more than
+pnpm's from-registry install.
+Caching behavior is changed via the build config in `catladder.ts`,
+not in the YAML.
+
+## Releases
+
+With `releases` configured, tagged releases are created by a release
+job (method: `semantic-release` or `changesets`). The release job also
+runs a dependency security audit that gates the release. See the
+`catladder-releases` skill for the full flow.
+
+## Debugging CI
+
+Useful CLI commands (see the `catladder-cli` skill for invocation):
+
+- `yarn catladder project ci job-log` / `project ci job-open` — fetch
+  or open a CI job
+- `yarn catladder project doctor` — detect drift between `catladder.ts`
+  and the actually provisioned infrastructure (missing IAM roles, stale
+  secrets, ...). Run this when a deploy/teardown fails with permission
+  errors even though the config looks right; fix findings with
+  `yarn catladder project setup [component]`.
+- `yarn catladder project logs open`, `project k8s list-pods`,
+  `project k8s get-shell` — inspect the running deployments
+
+## Related skills
+
+- `catladder-config` — catladder.ts structure and regeneration
+- `catladder-builds` — build jobs and Docker images
+- `catladder-deploys` — deploy jobs, environments and review apps
+- `catladder-releases` — the `taggedRelease` flow and security-audit gate
+- `catladder-secrets` — env vars and secret management
+- `catladder-cli` — non-interactive CLI usage and command reference
+- `catladder-migrate-ci-backend` — moving between GitLab CI and GitHub
+  Actions (running both in parallel, then cutting over)

package/dist/bundles/skills/catladder-releases/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: catladder-releases
+description: How releases work in a catladder project — the `releases` config in catladder.ts (manual vs automatic releasing, and the release method: semantic-release from conventional commits, or changesets from `.changeset/*.md` files), the version/tag/changelog flow, and the security-audit gate that every release must pass. Use when enabling or changing releases, deciding between semantic-release and changesets, writing changesets, cutting or debugging a release, or when a release job fails on the security audit. Triggers on "release", "releases config", "semantic-release", "changesets", "changeset", "version bump", "tag a release", "security audit", "release failed".
+---
+
+# Releases with catladder
+
+A release is what produces a `vX.Y.Z` git tag (with a changelog), which
+in turn triggers the `taggedRelease` pipeline that deploys to `stage`
+and `prod` (see the `catladder-pipelines` skill). Enable it in
+`catladder.ts`:
+
+```ts
+releases: {
+  when: "auto",              // "manual" (default) | "auto"
+  method: "semantic-release", // "semantic-release" (default) | "changesets"
+}
+```
+
+Change `catladder.ts` and regenerate (`yarn catenv`) — the release jobs
+are generated, never hand-edited.
+
+## `when` — who triggers the release
+
+- **`manual`** (default) — the `create release` job on the main branch
+  can be clicked **at any time**, even while the pipeline is still
+  running: it queues the release, which then runs automatically as soon
+  as every other job of the pipeline succeeded (and is skipped if the
+  pipeline fails). Clicking after a green pipeline releases right away.
+  - On GitLab the button is a quick no-op job; the actual release runs
+    in the automatic `🚀 release once pipeline succeeds` job (skipped
+    when the button was never clicked — never run it by hand).
+  - On GitHub, releasing is the **`🚀 catladder create release`**
+    workflow (Actions sidebar → Run workflow): it releases immediately
+    when the main workflow for HEAD is green, queues the release when
+    it is still running (the `🛠️ catladder release on green` workflow then
+    picks it up on completion), and fails when the run concluded red.
+- **`auto`** — the release job runs automatically on every main-branch
+  pipeline (it still no-ops when there is nothing to release).
+
+There is always also a **force release** escape hatch that releases
+**immediately**, ignoring the state of the pipeline: on GitLab the
+manual `⚠️ force create release` job, on GitHub the *force* checkbox of
+the `🚀 catladder create release` workflow. With `method: "changesets"`
+forcing has an extra meaning: it releases **even when no changesets are
+pending** (patch bump with a generic changelog entry) — the recovery
+path when a change was merged without a changeset and must ship now.
+
+On GitHub, other manual tasks are split into per-kind dispatch
+workflows the same way (`▶️ catladder deploy`, `⏹️ catladder stop`,
+`↩️ catladder rollback`), each with a dropdown of its tasks.
+
+## `method` — how the version is decided
+
+### `semantic-release` (default)
+The version is derived automatically from **conventional commit
+messages** since the last release (`fix:` → patch, `feat:` → minor,
+`BREAKING CHANGE` → major). Nothing to declare by hand — just write
+conventional commits.
+
+### `changesets`
+Developers declare changes intentionally as **`.changeset/*.md` files**
+(the official changesets format: a bump type + a human-written summary).
+The release job consumes all pending changesets, takes the highest bump,
+computes the next version from the last `v*` git tag, writes the
+changelog, commits `chore(release): <version>`, and pushes the tag. An
+empty `.changeset/` folder means there is nothing to release.
+
+Add a changeset by creating `.changeset/<name>.md`:
+
+```md
+---
+"my-app": minor
+---
+
+Add the new export endpoint.
+```
+
+**When you (an agent) make a user-facing change in a changesets
+project, add a changeset file in the same MR** — bump level `major`
+(breaking) / `minor` (feature) / `patch` (fix), and a one-to-two
+sentence summary written for the changelog reader. Docs/chore-only
+changes need none. The package name in the frontmatter is ignored
+(versions come from git tags); only the bump counts.
+
+### The changeset check (MR/PR pipelines)
+
+Changesets projects get a **`🦋 changeset check`** job in every
+merge-request pipeline. It reports what merging would do — the
+changesets this MR adds, everything pending, and the version the next
+release would get (with a changelog preview) — and **warns without
+blocking** (`allow_failure`) when the MR adds no changeset:
+
+- **GitLab**: report in the job log and as an exposed artifact
+  (`changeset-report.md`) in the MR widget. If the project makes
+  `GL_TOKEN` available to MR pipelines it also maintains a sticky MR
+  comment (opt-in — an api-scope token in MR pipelines is a security
+  trade-off).
+- **GitHub**: maintains a sticky PR comment via the workflow token; the
+  job stays green and reports a warning annotation (github has no
+  yellow job state, and a red job would read like a real failure).
+
+A yellow changeset-check job on an MR is a prompt to ask: is this
+change user-facing? If yes, add a changeset; if not, ignore it.
+
+## The security-audit gate
+
+**Both methods gate on a dependency security audit before releasing.**
+The release entrypoint runs the audit first; only if it passes does it
+create the version, changelog and tag. On GitLab, if the audit document
+is missing or invalid the job opens a merge request with a security-audit
+template and **fails** — resolve that MR, then re-run the release. See
+the `security` commands in the `catladder-cli` reference.
+
+## Debugging a failed release
+
+- Fails immediately on the audit → handle the security-audit gate above.
+- `changesets` released nothing → no `.changeset/*.md` files were
+  pending. To ship anyway, force the release (patch bump) — gitlab:
+  `⚠️ force create release` job, github: force checkbox — or merge an
+  MR adding a changeset describing the accumulated work.
+- Wrong version bump → check commit types (semantic-release) or the bump
+  levels in the changeset files (changesets).
+- Inspect the job with `yarn catladder project ci job-log` (see the
+  `catladder-cli` skill).
+
+## Related skills
+
+- `catladder-config` — catladder.ts structure and regeneration
+- `catladder-pipelines` — the `taggedRelease` trigger and stage/prod deploys
+- `catladder-cli` — `project ci` and `security` commands
+- `catladder-migrate-release-method` — switching an existing project
+  between semantic-release and changesets (incl. backfilling changesets
+  for everything merged since the last release tag)

package/dist/bundles/skills/catladder-secrets/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: catladder-secrets
+description: Managing environment variables and secrets in a catladder project. Use when adding or changing env vars in catladder.ts (vars.public / vars.secret), when a secret value must be set, rotated or checked, when secrets need syncing to GitHub, or when local .env / direnv environment questions come up. Triggers on "env var", "secret", "vars", "catenv", ".env", "config-secrets", "secrets-set", "secrets-list", "rotate a secret", "set a secret".
+---
+
+# Env vars and secrets with catladder
+
+Environment variables are declared per component in `catladder.ts`;
+secret *values* are never checked into the repo.
+
+## Declaring variables
+
+```ts
+components: {
+  app: {
+    vars: {
+      // names of secret vars — values are stored in the secrets vault, not in git
+      secret: ["API_KEY"],
+      public: {
+        MY_VAR: "some value",
+        // reference other vars, including from other components:
+        GRAPHQL_ENDPOINT: "${api:ROOT_URL}/graphql",
+      },
+    },
+  },
+}
+```
+
+Predefined per component/env: `ROOT_URL`, `HOSTNAME`, `PORT` (plus
+deploy-type specific ones). All vars are available at build time and at
+runtime. After changing declarations, regenerate with `yarn catenv` and
+commit.
+
+## Setting secret values
+
+Secret values are managed through the catladder CLI — never by editing
+files in the repo. All secrets commands accept a **scope**:
+`dev:web` (one env of one component), `dev:` (one env, all
+components), `:web` (all envs of one component), or nothing (everything).
+
+Check what is declared and what is still unset (never prints values
+unless `--reveal` is passed):
+
+```sh
+yarn catladder project secrets-list
+yarn catladder project secrets-list --check   # non-zero exit when something is unset
+```
+
+Set a single secret (the usual case — also for rotating one value
+across all envs via the `:component` scope):
+
+```sh
+echo -n "the-value" | yarn catladder project secrets-set dev:web API_KEY
+yarn catladder project secrets-set :web API_KEY --value-file /path/to/value
+```
+
+Prefer stdin or `--value-file` over `--value` so values stay out of
+shell history. **Never pass a real secret value you found in the
+conversation without the user having provided it for this purpose.**
+
+Bulk-edit several secrets as a YAML document
+(`component → env → key: value`):
+
+```sh
+yarn catladder project secrets-pull dev: --out /tmp/secrets.yml   # unset ones appear as "🚨 FILL ME"
+# edit the file, then:
+yarn catladder project secrets-push dev: --file /tmp/secrets.yml  # partial docs are fine
+```
+
+`secrets-push` skips placeholder/empty values, rejects undeclared
+keys, and may be partial — only the provided keys are written. Both
+support `--key KEY1,KEY2` to narrow further. Delete the temp file
+afterwards; never commit it.
+
+Humans may instead use the interactive editor flow
+(`project config-secrets`, opens `$EDITOR`); as an agent, use the
+commands above.
+
+All of these write to the secrets vault (the source of truth) and
+automatically mirror to the enabled CI backends — which vault is
+configured makes no difference to the commands.
+
+## GitHub pipelines
+
+GitHub Actions cannot read the vault at runtime; secrets are mirrored
+into GitHub *environment* secrets (one GitHub environment per catladder
+env). Sync them with:
+
+```sh
+yarn catladder project secrets-sync-github
+```
+
+Run this after adding/changing secrets when a github pipeline is
+enabled.
+
+## Local development
+
+`catenv` generates the local env (`.env` files / exported vars via
+direnv) for the `local` environment. If a var is missing locally,
+check its declaration in `catladder.ts` and re-run `yarn catenv` before
+suspecting anything else.
+
+## Related skills
+
+- `catladder-config` — general catladder.ts structure and regeneration
+- `catladder-builds` — build-time vars (`jobVars`) and build config
+- `catladder-deploys` — runtime deploy config
+- `catladder-pipelines` — how the generated pipelines work
+- `catladder-cli` — non-interactive CLI usage and command reference
+- `catladder-migrate-ci-backend` — moving between CI backends (the vault
+  is what blocks decommissioning the old one)

package/dist/packages/bash/src/BashExpression.d.ts

@@ -0,0 +1,36 @@
+/**
+ * this class represents a string that can be evaluated in bash scripts.
+ *
+ * you can do basic transforms like lowercase, but that does not return you a lowercase string, but instead an experssion represeting a lowercase string
+ */
+export declare class BashExpression {
+    private value;
+    constructor(value: string | BashExpression);
+    toJSON(): string;
+    toString(): string;
+    replace(searchValue: any, replacer: (substring: string, ...args: any[]) => string): BashExpression;
+    /**
+     *
+     * @returns a bash expression to lowercase the string
+     */
+    toLowerCase(): BashExpression;
+    /**
+     * concats a value to this one and returns a new BashExpression
+     * @param value
+     * @returns
+     */
+    concat(...values: Array<string | BashExpression>): BashExpression;
+    transformWithCommand(command: string): BashExpression;
+}
+export type StringOrBashExpression = string | BashExpression;
+export declare const getBashVariable: (name: string) => BashExpression;
+/**
+ * joins bash expressions together with a joiner
+ * returns a bash expression if any of the parts is a bash expression
+ * returns a string otherwise
+ *
+ * @param parts
+ * @param joiner
+ * @returns
+ */
+export declare const joinBashExpressions: (parts: Array<StringOrBashExpression>, joiner?: string) => StringOrBashExpression;

package/dist/packages/bash/src/BashExpression.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.joinBashExpressions = exports.getBashVariable = exports.BashExpression = void 0;
+/**
+ * this class represents a string that can be evaluated in bash scripts.
+ *
+ * you can do basic transforms like lowercase, but that does not return you a lowercase string, but instead an experssion represeting a lowercase string
+ */
+class BashExpression {
+    constructor(value) {
+        this.value = value;
+    }
+    toJSON() {
+        return this.toString();
+    }
+    toString() {
+        return this.value.toString();
+    }
+    replace(searchValue, replacer) {
+        return new BashExpression(this.value.toString().replace(searchValue, replacer));
+    }
+    /**
+     *
+     * @returns a bash expression to lowercase the string
+     */
+    toLowerCase() {
+        return this.transformWithCommand("awk '{print tolower($0)}'");
+    }
+    /**
+     * concats a value to this one and returns a new BashExpression
+     * @param value
+     * @returns
+     */
+    concat(...values) {
+        return new BashExpression(this.toString().concat(...values.map((v) => v.toString())));
+    }
+    transformWithCommand(command) {
+        return new BashExpression(
+        // see https://stackoverflow.com/a/2264537
+        `$(printf %s "${this.toString()}" | ${command})`);
+    }
+}
+exports.BashExpression = BashExpression;
+const getBashVariable = (name) => new BashExpression(`$${name}`);
+exports.getBashVariable = getBashVariable;
+/**
+ * joins bash expressions together with a joiner
+ * returns a bash expression if any of the parts is a bash expression
+ * returns a string otherwise
+ *
+ * @param parts
+ * @param joiner
+ * @returns
+ */
+const joinBashExpressions = (parts, joiner = "") => {
+    const anyIsBashExpression = parts.some((p) => p instanceof BashExpression);
+    if (anyIsBashExpression) {
+        return new BashExpression(parts
+            .map((p) => (p instanceof BashExpression ? p.toString() : p))
+            .join(joiner));
+    }
+    else {
+        return parts.join(joiner);
+    }
+};
+exports.joinBashExpressions = joinBashExpressions;
+//# sourceMappingURL=BashExpression.js.map

package/dist/packages/bash/src/BashExpression.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BashExpression.js","sourceRoot":"","sources":["../../../../../../packages/bash/src/BashExpression.ts"],"names":[],"mappings":";;;AAAA;;;;GAIG;AACH,MAAa,cAAc;IACzB,YAAoB,KAA8B;QAA9B,UAAK,GAAL,KAAK,CAAyB;IAAG,CAAC;IAC/C,MAAM;QACX,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC;IACzB,CAAC;IACM,QAAQ;QACb,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;IAC/B,CAAC;IAEM,OAAO,CACZ,WAAgB,EAEhB,QAAuD;QAEvD,OAAO,IAAI,cAAc,CACvB,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,QAAQ,CAAC,CACrD,CAAC;IACJ,CAAC;IAED;;;OAGG;IACI,WAAW;QAChB,OAAO,IAAI,CAAC,oBAAoB,CAAC,2BAA2B,CAAC,CAAC;IAChE,CAAC;IACD;;;;OAIG;IACI,MAAM,CAAC,GAAG,MAAsC;QACrD,OAAO,IAAI,cAAc,CACvB,IAAI,CAAC,QAAQ,EAAE,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAC3D,CAAC;IACJ,CAAC;IAEM,oBAAoB,CAAC,OAAe;QACzC,OAAO,IAAI,cAAc;QACvB,0CAA0C;QAC1C,gBAAgB,IAAI,CAAC,QAAQ,EAAE,OAAO,OAAO,GAAG,CACjD,CAAC;IACJ,CAAC;CACF;AA3CD,wCA2CC;AAIM,MAAM,eAAe,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,IAAI,cAAc,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;AAAnE,QAAA,eAAe,mBAAoD;AAEhF;;;;;;;;GAQG;AACI,MAAM,mBAAmB,GAAG,CACjC,KAAoC,EACpC,MAAM,GAAG,EAAE,EACa,EAAE;IAC1B,MAAM,mBAAmB,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,YAAY,cAAc,CAAC,CAAC;IAC3E,IAAI,mBAAmB,EAAE,CAAC;QACxB,OAAO,IAAI,cAAc,CACvB,KAAK;aACF,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;aAC5D,IAAI,CAAC,MAAM,CAAC,CAChB,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,OAAO,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5B,CAAC;AACH,CAAC,CAAC;AAdW,QAAA,mBAAmB,uBAc9B"}

package/dist/packages/bash/src/bashEscape.d.ts

@@ -0,0 +1,37 @@
+import type { VariableValue } from "./variables/VariableValue";
+import { BashExpression } from "./BashExpression";
+export type QuotesEscapeMode = "single" | "double";
+export type EscapeOptions = {
+    quotes?: QuotesEscapeMode | false;
+};
+/**
+ * escapes a string or bash expression for bash
+ * it either can escape single or double quotes (double is default)
+ */
+export declare const bashEscape: (value: VariableValue | any, options?: EscapeOptions) => string | BashExpression;
+export declare const escapeString: (value: string | null | undefined, { quotes }?: EscapeOptions) => string;
+export declare const escapeBashExpression: (value: BashExpression, options: EscapeOptions) => BashExpression;
+export declare const escapeDoubleQuotes: (value: string | null | undefined) => string;
+export declare const escapeSingleQuotes: (value: string | null | undefined) => string;
+export declare const escapeBackTicks: (value: string | null | undefined) => string;
+export declare const escapeNewlines: (value: string | null | undefined) => string;
+export type EscapeForDotEnvOptions = {
+    quoteMode: "auto" | "always";
+};
+/**
+ *
+ * escape env vars for .env files.
+ * unfortunatly, the format has many limitations. In order to be very forgiving, we need to do some magic here:
+ *
+ * - when the value contains no newlines, we are fine
+ * - if the value contains newlines, we need to wrap it in quotes. And thats where the problem begins:
+ * - you can't escape quotes. this is a limitation of dotenv and node
+ * - you can have inner quotes, but they break in node.js (not in dotenv though), see https://github.com/nodejs/node/issues/54134
+ * - so we need to quote cleverly
+ * - to make things worse, we need to check whether we have a simple stirng or a bash expression, that needs to be evalulated first...
+ *
+ *  what an absolute nightmare.
+ *
+ * - other languages are currently only partially supported, since most .env implementations are slightly different
+ */
+export declare const escapeForDotEnv: (value: VariableValue | undefined | null, options?: EscapeForDotEnvOptions) => string;

package/dist/packages/bash/src/bashEscape.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escapeForDotEnv = exports.escapeNewlines = exports.escapeBackTicks = exports.escapeSingleQuotes = exports.escapeDoubleQuotes = exports.escapeBashExpression = exports.escapeString = exports.bashEscape = void 0;
+const globalScriptFunctions_1 = require("./globalScriptFunctions");
+const VariableValueContainingReferences_1 = require("./variables/VariableValueContainingReferences");
+const BashExpression_1 = require("./BashExpression");
+/**
+ * escapes a string or bash expression for bash
+ * it either can escape single or double quotes (double is default)
+ */
+const bashEscape = (value, options = {
+    quotes: "double",
+}) => {
+    if (value instanceof BashExpression_1.BashExpression) {
+        // no need to escape
+        return (0, exports.escapeBashExpression)(value, options);
+    }
+    if (value instanceof VariableValueContainingReferences_1.VariableValueContainingReferences) {
+        return value.toString(options);
+    }
+    return (0, exports.escapeString)(value, options);
+};
+exports.bashEscape = bashEscape;
+const escapeString = (value, { quotes } = {
+    quotes: "double",
+}) => {
+    const quoteEscaped = quotes
+        ? quotes === "single"
+            ? (0, exports.escapeSingleQuotes)(value)
+            : (0, exports.escapeDoubleQuotes)(value)
+        : value;
+    return quoteEscaped;
+};
+exports.escapeString = escapeString;
+const escapeBashExpression = (value, options) => {
+    // no need to escape, we just return the string
+    return value;
+};
+exports.escapeBashExpression = escapeBashExpression;
+const escapeDoubleQuotes = (value) => value === null || value === void 0 ? void 0 : value.toString().replace(/"/g, '\\"');
+exports.escapeDoubleQuotes = escapeDoubleQuotes;
+const escapeSingleQuotes = (value) => value === null || value === void 0 ? void 0 : value.toString().replace(/'/g, "\\'");
+exports.escapeSingleQuotes = escapeSingleQuotes;
+const escapeBackTicks = (value) => value === null || value === void 0 ? void 0 : value.toString().replace(/`/g, "\\`");
+exports.escapeBackTicks = escapeBackTicks;
+const escapeNewlines = (value) => value === null || value === void 0 ? void 0 : value.toString().replace(/\n/g, "\\n");
+exports.escapeNewlines = escapeNewlines;
+/**
+ *
+ * escape env vars for .env files.
+ * unfortunatly, the format has many limitations. In order to be very forgiving, we need to do some magic here:
+ *
+ * - when the value contains no newlines, we are fine
+ * - if the value contains newlines, we need to wrap it in quotes. And thats where the problem begins:
+ * - you can't escape quotes. this is a limitation of dotenv and node
+ * - you can have inner quotes, but they break in node.js (not in dotenv though), see https://github.com/nodejs/node/issues/54134
+ * - so we need to quote cleverly
+ * - to make things worse, we need to check whether we have a simple stirng or a bash expression, that needs to be evalulated first...
+ *
+ *  what an absolute nightmare.
+ *
+ * - other languages are currently only partially supported, since most .env implementations are slightly different
+ */
+const escapeForDotEnv = (value, options = {
+    quoteMode: "auto",
+}) => {
+    if (value === undefined || value === null) {
+        return "";
+    }
+    if (typeof value === "string") {
+        // if string contains newlines, we need to wrap it in quotes
+        // we additionaly escape newlines, that give best compatibility
+        if (options.quoteMode === "always" || value.includes("\n")) {
+            const newlinesReplaces = value.replace(/\n/g, "\\n");
+            // default to ", but if this is not possible, we try to use ' or `
+            const quote = value.includes(`"`)
+                ? value.includes(`'`)
+                    ? value.includes("`")
+                        ? // If all quote types are present, default to double quotes. This works in dotenv, but not in node.js because of the bug mentioned abouve
+                            '"'
+                        : "`"
+                    : "'"
+                : '"';
+            // if we found a quote, we can wrap the string in it
+            return `${quote}${newlinesReplaces}${quote}`;
+        }
+        else {
+            // otherwise we can return as is
+            return value;
+        }
+    }
+    else if (value instanceof BashExpression_1.BashExpression) {
+        return escapeBashExpressionForDotEnv(value);
+    }
+    else if (value instanceof VariableValueContainingReferences_1.VariableValueContainingReferences) {
+        // instead of doing it part-wise, we just do it all at once
+        const containsAnyBashExpression = value.parts.some((part) => part instanceof BashExpression_1.BashExpression);
+        if (!containsAnyBashExpression) {
+            // all parts are literal: the value never passes through bash, so it
+            // must NOT be bash-escaped — `quotes: "double"` would bake literal
+            // \" into the env value (e.g. JSON values, since the deterministic
+            // cloud run urls made such values fully literal)
+            return (0, exports.escapeForDotEnv)(value.toString({
+                quotes: false,
+            }));
+        }
+        else {
+            const result = escapeBashExpressionForDotEnv(new BashExpression_1.BashExpression(value.toString({
+                quotes: "double",
+            })));
+            return result;
+        }
+    }
+    else {
+        return value;
+    }
+};
+exports.escapeForDotEnv = escapeForDotEnv;
+// basically the same thing as above for bash
+// thx chatgpt for this
+const escapeForDotEnvScript = (0, globalScriptFunctions_1.registerGlobalScriptFunction)("escapeForDotEnv", `
+ input="\${1:-$(cat)}"
+ input="\${input//$'\\n'/\\\\n}"
+  if [[ "$input" == *\\\\n* ]]; then
+    if [[ "$input" == *\\"* && "$input" == *\\'* && "$input" == *\\\`* ]]; then
+      printf "\\"%s\\"\\n" "$input" ${ /* fallback to double quotes */""}
+    elif [[ "$input" == *\\"* && "$input" == *\\'* ]]; then
+      printf "\`%s\`\\n" "$input"
+    elif [[ "$input" == *\\"* ]]; then
+      printf "'%s'\\n" "$input"
+    else
+      printf "\\"%s\\"\\n" "$input"
+    fi
+  else
+    printf "%s\\n" "$input"
+  fi
+  `);
+const escapeBashExpressionForDotEnv = (value) => {
+    return value.transformWithCommand(escapeForDotEnvScript.name).toString();
+};
+//# sourceMappingURL=bashEscape.js.map

package/dist/packages/bash/src/bashEscape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bashEscape.js","sourceRoot":"","sources":["../../../../../../packages/bash/src/bashEscape.ts"],"names":[],"mappings":"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"}

package/dist/packages/bash/src/bashYaml.d.ts

@@ -0,0 +1,10 @@
+/***
+ * creates a yaml string that can be used in bash scripts
+ * it handles BashExpressions correctly so that they can be evaluated in bash
+ */
+export declare const yamlBashString: (value: any) => string;
+/**
+ * creates a bash script that writes a yaml string to a file
+ * @param value the yaml value to write, it supports BashExpressions
+ */
+export declare const writeBashYamlToFileScript: (value: any, filename: string) => string[];