@kindgi/cli 0.0.0-bootstrap.0 → 0.1.0

package/dist/env/pack-env-plan.js

@@ -0,0 +1,236 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * The process environment a deployed pack service gets: each name the
+ * pack declares (`env.required` / `env.optional` in `kindgi.config`) and
+ * where its value comes from in a target environment
+ * (`environments.<name>.env`):
+ *
+ *   - a plain value, for what isn't secret (committed, and visible in the
+ *     deployed revision);
+ *   - `{ secret, version, project? }`, a Secret Manager secret the operator
+ *     created, which the platform resolves with the pack service's own
+ *     identity. Kindgi never reads, stores or generates its value.
+ *
+ * Only declared names are injected. A secret given as a plain value is
+ * refused, by its name (`*_KEY`, `*_TOKEN`, …) or by a credential inside
+ * it (a URL with a password), so it goes by reference.
+ */
+import { resolvePackEnv } from '@kindgi/handler-runtime';
+/** Names operators commonly give to real secrets. */
+const SECRET_SHAPED_NAME = /_(?:KEY|SECRET|TOKEN|PASSWORD|PRIVATE|APIKEY|API_KEY)$/i;
+/** A Secret Manager secret id. */
+const SECRET_ID = /^[A-Za-z0-9_-]{1,255}$/;
+const VERSION = /^(?:latest|[1-9][0-9]*)$/;
+const PROJECT_NUMBER = /^[0-9]+$/;
+/** Whether a name looks like it holds a secret (`*_KEY`, `*_TOKEN`, `*_PASSWORD`, …). */
+export function isSecretShapedName(name) {
+    return SECRET_SHAPED_NAME.test(name);
+}
+/** Whether a value carries a credential: a URL with a password (`postgres://user:pass@host/db`). */
+export function carriesCredential(value) {
+    if (!/^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(value))
+        return false;
+    try {
+        return new URL(value).password !== '';
+    }
+    catch {
+        return /^[^:/]+:\/\/[^/@]*:[^/@]*@/.test(value);
+    }
+}
+/**
+ * Why `value` can't be given in the clear under `name`, or `undefined`
+ * when it can. The one check behind `kindgi env plan`, the deploy
+ * preflight and `kindgi deploy --sync-secrets`'s warning.
+ */
+export function plainSecretReason(name, value) {
+    if (carriesCredential(value))
+        return `${name}'s value has a credential in it (a URL with a password)`;
+    if (isSecretShapedName(name))
+        return `${name} is named like a secret`;
+    return undefined;
+}
+/** `environments.<envName>.env` from a loaded config: each name's source, and what's malformed. */
+export function readEnvironmentEnv(config, envName) {
+    const sources = new Map();
+    const problems = [];
+    const environments = config?.environments;
+    const block = environments !== null && typeof environments === 'object'
+        ? environments[envName]
+        : undefined;
+    const env = block !== null && typeof block === 'object'
+        ? block.env
+        : undefined;
+    if (env === undefined)
+        return { sources, problems };
+    if (env === null || typeof env !== 'object' || Array.isArray(env)) {
+        return { sources, problems: [`environments.${envName}.env must be an object`] };
+    }
+    for (const [name, raw] of Object.entries(env)) {
+        const at = `environments.${envName}.env.${name}`;
+        if (typeof raw === 'string') {
+            sources.set(name, { kind: 'value', value: raw });
+            continue;
+        }
+        const source = readSecretSource(at, raw);
+        if (typeof source === 'string')
+            problems.push(source);
+        else
+            sources.set(name, source);
+    }
+    return { sources, problems };
+}
+function readSecretSource(at, raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        return `${at} must be a string or { secret, version, project? }`;
+    }
+    const { secret, version, project, ...rest } = raw;
+    const extra = Object.keys(rest);
+    if (extra.length > 0)
+        return `${at} takes secret, version and project, not ${extra.join(', ')}`;
+    if (typeof secret !== 'string' || !SECRET_ID.test(secret)) {
+        return `${at}.secret must be a Secret Manager secret id (letters, digits, _ and -)`;
+    }
+    if (typeof version !== 'string' || !VERSION.test(version)) {
+        return `${at}.version must be a version number (e.g. "3") or "latest"`;
+    }
+    if (project !== undefined && (typeof project !== 'string' || !PROJECT_NUMBER.test(project))) {
+        return `${at}.project must be a project number: Cloud Run names another project's secret by number`;
+    }
+    return {
+        kind: 'secret',
+        secret,
+        version,
+        ...(typeof project === 'string' && { project }),
+    };
+}
+/**
+ * The plan for `envName`: the pack's declaration (from `config.env`)
+ * against that environment's sources. `err` when the declaration itself
+ * is malformed, the same check the indexer runs.
+ */
+export function planPackEnv(config, envName) {
+    const declared = resolvePackEnv(config?.env);
+    if (declared.kind === 'err')
+        return { kind: 'err', message: `kindgi.config: ${declared.message}` };
+    const declaration = declared.value ?? { required: [], optional: [] };
+    const { sources, problems: malformed } = readEnvironmentEnv(config, envName);
+    const problems = [...malformed];
+    const warnings = [];
+    const entries = [];
+    const add = (name, required) => {
+        const source = sources.get(name);
+        entries.push({ name, required, ...(source !== undefined && { source }) });
+        if (source?.kind === 'value') {
+            const reason = plainSecretReason(name, source.value);
+            if (reason !== undefined) {
+                problems.push(`${reason}: give it as { secret, version } in environments.${envName}.env`);
+            }
+        }
+        if (source?.kind === 'secret' && source.version === 'latest') {
+            warnings.push(`${name} uses the latest version of ${source.secret}: it's read when an instance starts, so a new version needs a new revision`);
+        }
+    };
+    for (const name of declaration.required)
+        add(name, true);
+    for (const name of declaration.optional)
+        add(name, false);
+    const declaredNames = new Set([...declaration.required, ...declaration.optional]);
+    for (const name of sources.keys()) {
+        if (!declaredNames.has(name)) {
+            warnings.push(`environments.${envName}.env.${name} isn't declared in env.required or env.optional, so it isn't injected`);
+        }
+    }
+    const missing = entries.filter((e) => e.required && e.source === undefined).map((e) => e.name);
+    return { kind: 'ok', plan: { envName, entries, missing, problems, warnings } };
+}
+/** A secret source as Cloud Run takes it: `SECRET:VERSION`, or the full name for another project. */
+export function secretReference(source) {
+    const secret = source.project === undefined
+        ? source.secret
+        : `projects/${source.project}/secrets/${source.secret}`;
+    return `${secret}:${source.version}`;
+}
+/**
+ * The Terraform input for the pack service's revision: `env` (plain
+ * values) and `secret_env` (references), as JSON.
+ */
+export function renderTerraform(plan) {
+    const env = {};
+    const secretEnv = {};
+    for (const entry of plan.entries) {
+        const source = entry.source;
+        if (source?.kind === 'value')
+            env[entry.name] = source.value;
+        if (source?.kind === 'secret') {
+            secretEnv[entry.name] = {
+                secret: source.secret,
+                version: source.version,
+                ...(source.project !== undefined && { project: source.project }),
+            };
+        }
+    }
+    return `${JSON.stringify({ env, secret_env: secretEnv }, null, 2)}\n`;
+}
+/** `gcloud run deploy` flags: `--set-env-vars` and `--set-secrets`, one per line. */
+export function renderGcloud(plan) {
+    const values = [];
+    const secrets = [];
+    for (const entry of plan.entries) {
+        const source = entry.source;
+        if (source?.kind === 'value')
+            values.push(`${entry.name}=${source.value}`);
+        if (source?.kind === 'secret')
+            secrets.push(`${entry.name}=${secretReference(source)}`);
+    }
+    const lines = [];
+    if (values.length > 0)
+        lines.push(`--set-env-vars=${joinForGcloud(values)}`);
+    if (secrets.length > 0)
+        lines.push(`--set-secrets=${joinForGcloud(secrets)}`);
+    return lines.length > 0 ? `${lines.join(' \\\n')}\n` : '';
+}
+/**
+ * gcloud splits a list on commas; a value with a comma needs another
+ * delimiter, given as `^DELIM^` in front of the list.
+ */
+function joinForGcloud(items) {
+    if (!items.some((item) => item.includes(',')))
+        return items.join(',');
+    const delimiter = ['@', '|', ';', '#', '~'].find((d) => !items.some((item) => item.includes(d)));
+    if (delimiter === undefined) {
+        throw new Error('a value contains every gcloud list delimiter Kindgi tries; set it by hand');
+    }
+    return `^${delimiter}^${items.join(delimiter)}`;
+}
+/** The plan as lines for a terminal: one per declared name, then what's wrong and worth knowing. */
+/** Where an entry's value comes from, for a terminal. A secret given in the clear is never shown. */
+function describeSource(entry) {
+    const source = entry.source;
+    if (source === undefined)
+        return entry.required ? '✗ no value' : '(unset: not injected)';
+    if (source.kind === 'secret')
+        return `secret ${secretReference(source)}`;
+    return plainSecretReason(entry.name, source.value) === undefined
+        ? `value ${JSON.stringify(source.value)}`
+        : '✗ value withheld: a secret in the clear';
+}
+export function describePackEnvPlan(plan) {
+    const lines = [`  The pack service's env in ${plan.envName}:`];
+    if (plan.entries.length === 0) {
+        lines.push('    (the pack declares none: add env.required / env.optional to kindgi.config)');
+    }
+    for (const entry of plan.entries) {
+        const kind = entry.required ? 'required' : 'optional';
+        lines.push(`    ${kind.padEnd(8)}  ${entry.name.padEnd(28)}  ${describeSource(entry)}`);
+    }
+    for (const name of plan.missing) {
+        lines.push(`  ✗ ${name} is required and has no value in environments.${plan.envName}.env`);
+    }
+    for (const problem of plan.problems)
+        lines.push(`  ✗ ${problem}`);
+    for (const warning of plan.warnings)
+        lines.push(`  ⚠ ${warning}`);
+    return lines;
+}
+//# sourceMappingURL=pack-env-plan.js.map

package/dist/env/pack-env-plan.js.map

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

package/dist/env/parser.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Re-exports the shared dotenv parser from `@kindgi/dotenv-file`. The
+ * grammar + serialization rules are the same across `kindgi env`
+ * subcommands and the dev-mode `SecretBinding` in `@kindgi/secrets-dotenv`
+ * — extracting the primitive prevents drift between what the CLI writes
+ * and what the binding reads.
+ */
+export { ENV_KEY_REGEX, type EnvLine, envLinesToRecord, parseEnvFile, serializeEnvFile, } from '@kindgi/dotenv-file';
+//# sourceMappingURL=parser.d.ts.map

package/dist/env/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/env/parser.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AAEH,OAAO,EACL,aAAa,EACb,KAAK,OAAO,EACZ,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,GACjB,MAAM,qBAAqB,CAAC"}

package/dist/env/parser.js

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * Re-exports the shared dotenv parser from `@kindgi/dotenv-file`. The
+ * grammar + serialization rules are the same across `kindgi env`
+ * subcommands and the dev-mode `SecretBinding` in `@kindgi/secrets-dotenv`
+ * — extracting the primitive prevents drift between what the CLI writes
+ * and what the binding reads.
+ */
+export { ENV_KEY_REGEX, envLinesToRecord, parseEnvFile, serializeEnvFile, } from '@kindgi/dotenv-file';
+//# sourceMappingURL=parser.js.map

package/dist/env/parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../../src/env/parser.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC;;;;;;GAMG;AAEH,OAAO,EACL,aAAa,EAEb,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,GACjB,MAAM,qBAAqB,CAAC"}

package/dist/env/project-env.d.ts

@@ -0,0 +1,34 @@
+/**
+ * CLI side of the pack env files (`@kindgi/secrets-dotenv`'s
+ * `readPackEnv`): which files a command reads for an environment, and
+ * how their warnings are shown.
+ *
+ * Warnings name `file:line` and a reason — never the line's text. The
+ * files are the project's own `.env`s and a malformed line can be a
+ * secret with a typo in it.
+ */
+import type { EnvDiagnostic } from '@kindgi/dotenv-file';
+import type { CommandContext } from '../context.js';
+import { type PackConfigRecord } from '../pack-config.js';
+export type LocalEnvSettings = {
+    readonly kind: 'ok';
+    /** The loaded config, when there is a valid one. */
+    readonly config: PackConfigRecord | undefined;
+    /** `dev.envFiles`, when set. */
+    readonly localEnvFiles: readonly string[] | undefined;
+    /** Set when the config exists but could not be loaded. */
+    readonly configProblem: string | undefined;
+} | {
+    readonly kind: 'error';
+    readonly message: string;
+};
+/**
+ * Load the pack config and its `dev.envFiles`. A missing or unloadable
+ * config yields the defaults (`configProblem` says why, for callers
+ * that want to fail or warn); a present-but-malformed `dev.envFiles` is
+ * always an error — the author asked for specific files.
+ */
+export declare function loadLocalEnvSettings(ctx: Pick<CommandContext, 'buildConfigLoader'>, packDir: string): Promise<LocalEnvSettings>;
+/** One human-readable line per diagnostic, safe to print. */
+export declare function describeEnvDiagnostics(packDir: string, diagnostics: readonly EnvDiagnostic[]): string[];
+//# sourceMappingURL=project-env.d.ts.map

package/dist/env/project-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-env.d.ts","sourceRoot":"","sources":["../../src/env/project-env.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,KAAK,gBAAgB,EAA+B,MAAM,mBAAmB,CAAC;AAEvF,MAAM,MAAM,gBAAgB,GACxB;IACE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAC9C,gCAAgC;IAChC,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACtD,0DAA0D;IAC1D,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5C,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,mBAAmB,CAAC,EAC9C,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,gBAAgB,CAAC,CAkB3B;AAED,6DAA6D;AAC7D,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,SAAS,aAAa,EAAE,GACpC,MAAM,EAAE,CAYV"}

package/dist/env/project-env.js

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { displayEnvPath } from '@kindgi/secrets-dotenv';
+import { devEnvFiles, loadPackConfig } from '../pack-config.js';
+/**
+ * Load the pack config and its `dev.envFiles`. A missing or unloadable
+ * config yields the defaults (`configProblem` says why, for callers
+ * that want to fail or warn); a present-but-malformed `dev.envFiles` is
+ * always an error — the author asked for specific files.
+ */
+export async function loadLocalEnvSettings(ctx, packDir) {
+    const outcome = await loadPackConfig(ctx, packDir);
+    if (outcome.kind !== 'ok') {
+        return {
+            kind: 'ok',
+            config: undefined,
+            localEnvFiles: undefined,
+            configProblem: outcome.kind === 'invalid' ? outcome.message : undefined,
+        };
+    }
+    const files = devEnvFiles(outcome.config);
+    if (files.kind === 'invalid')
+        return { kind: 'error', message: files.message };
+    return {
+        kind: 'ok',
+        config: outcome.config,
+        localEnvFiles: files.files,
+        configProblem: undefined,
+    };
+}
+/** One human-readable line per diagnostic, safe to print. */
+export function describeEnvDiagnostics(packDir, diagnostics) {
+    return diagnostics.map((d) => {
+        const file = displayEnvPath(packDir, d.source);
+        switch (d.kind) {
+            case 'malformed':
+                return `${file}:${d.line}: ignored — ${d.reason}`;
+            case 'unresolved':
+                return `${file}: ${d.key} references \${${d.ref}}, which no env file (or the environment) defines — expanded to ""`;
+            case 'cycle':
+                return `${file}: ${d.key} references \${${d.ref}} in a cycle — the reference expanded to ""`;
+        }
+    });
+}
+//# sourceMappingURL=project-env.js.map

package/dist/env/project-env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-env.js","sourceRoot":"","sources":["../../src/env/project-env.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAajC,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAGxD,OAAO,EAAyB,WAAW,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAcvF;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,GAA8C,EAC9C,OAAe;IAEf,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACnD,IAAI,OAAO,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;QAC1B,OAAO;YACL,IAAI,EAAE,IAAI;YACV,MAAM,EAAE,SAAS;YACjB,aAAa,EAAE,SAAS;YACxB,aAAa,EAAE,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;SACxE,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAG,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1C,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;IAC/E,OAAO;QACL,IAAI,EAAE,IAAI;QACV,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,aAAa,EAAE,KAAK,CAAC,KAAK;QAC1B,aAAa,EAAE,SAAS;KACzB,CAAC;AACJ,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,sBAAsB,CACpC,OAAe,EACf,WAAqC;IAErC,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QAC3B,MAAM,IAAI,GAAG,cAAc,CAAC,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC;QAC/C,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;YACf,KAAK,WAAW;gBACd,OAAO,GAAG,IAAI,IAAI,CAAC,CAAC,IAAI,eAAe,CAAC,CAAC,MAAM,EAAE,CAAC;YACpD,KAAK,YAAY;gBACf,OAAO,GAAG,IAAI,KAAK,CAAC,CAAC,GAAG,kBAAkB,CAAC,CAAC,GAAG,oEAAoE,CAAC;YACtH,KAAK,OAAO;gBACV,OAAO,GAAG,IAAI,KAAK,CAAC,CAAC,GAAG,kBAAkB,CAAC,CAAC,GAAG,6CAA6C,CAAC;QACjG,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/env/runners.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Injectable seams for `kindgi env`. Every filesystem side-effect
+ * flows through this shape so tests substitute fixtures — no real
+ * `.env.<envName>` files touch disk during unit tests.
+ *
+ * Production wiring lives at `packages/cli/src/env/defaults.ts`; tests
+ * pass `RunCliInputs.envRunners` with in-memory stubs.
+ */
+export interface EnvRunners {
+    /**
+     * Read `path` as UTF-8. Returns `null` when the file does not exist;
+     * throws for any other IO error.
+     */
+    readonly readFile: (path: string) => Promise<string | null>;
+    /**
+     * Write `contents` to `path`. `mkdir -p` on the parent dir is the
+     * caller's job (env files sit next to `kindgi.config.ts`, which
+     * always exists).
+     */
+    readonly writeFile: (path: string, contents: string) => Promise<void>;
+}
+//# sourceMappingURL=runners.d.ts.map

package/dist/env/runners.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runners.d.ts","sourceRoot":"","sources":["../../src/env/runners.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AAEH,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5D;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvE"}

package/dist/env/runners.js

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+export {};
+//# sourceMappingURL=runners.js.map

package/dist/env/runners.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runners.js","sourceRoot":"","sources":["../../src/env/runners.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC"}

package/dist/env/writer.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `.env.<envName>` set / unset primitives — re-exported from the shared
+ * `@kindgi/dotenv-file` package so `kindgi env` and the dev-mode
+ * `SecretBinding` in `@kindgi/secrets-dotenv` agree on the write shape.
+ */
+export { EnvValueNotRepresentableError, setKey, unsetKey } from '@kindgi/dotenv-file';
+//# sourceMappingURL=writer.d.ts.map

package/dist/env/writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.d.ts","sourceRoot":"","sources":["../../src/env/writer.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AAEH,OAAO,EAAE,6BAA6B,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/env/writer.js

@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * `.env.<envName>` set / unset primitives — re-exported from the shared
+ * `@kindgi/dotenv-file` package so `kindgi env` and the dev-mode
+ * `SecretBinding` in `@kindgi/secrets-dotenv` agree on the write shape.
+ */
+export { EnvValueNotRepresentableError, setKey, unsetKey } from '@kindgi/dotenv-file';
+//# sourceMappingURL=writer.js.map

package/dist/env/writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.js","sourceRoot":"","sources":["../../src/env/writer.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC;;;;GAIG;AAEH,OAAO,EAAE,6BAA6B,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,31 @@
+import { type KindgiError } from '@kindgi/client';
+/**
+ * The CLI-level exit envelope. Every command handler returns one so the
+ * top-level dispatcher can pick exit codes and write stdout/stderr
+ * exactly once.
+ */
+export interface CliError {
+    readonly kind: 'error';
+    readonly exitCode: number;
+    readonly stderr: string;
+    readonly stdout?: string;
+}
+export declare function cliError(message: string, exitCode?: number): CliError;
+/**
+ * Format any thrown value into an error envelope suitable for CLI
+ * output. Recognises the SDK's `KindgiApiError` (typed wire error),
+ * plus the preview stub (`not-implemented-in-preview`), and falls back
+ * to raw `Error.message` for anything else.
+ */
+export declare function formatThrown(thrown: unknown, options: {
+    readonly verbose?: boolean;
+    readonly commandLabel: string;
+}): CliError;
+/**
+ * The SDK's `notImplementedInPreview()` currently returns a plain POJO
+ * (`{ code, message, method }`) that is `throw`n as-is — not wrapped
+ * in `KindgiApiError`. Recognise both shapes so callers see uniform
+ * error output.
+ */
+export declare function extractKindgiError(thrown: unknown): KindgiError | null;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAGA,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElE;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,QAAQ,CAEhE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,OAAO,EACf,OAAO,EAAE;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GACrE,QAAQ,CA2BV;AAqDD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI,CAatE"}

package/dist/errors.js

@@ -0,0 +1,107 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { KindgiApiError } from '@kindgi/client';
+export function cliError(message, exitCode = 1) {
+    return { kind: 'error', exitCode, stderr: `${message}\n` };
+}
+/**
+ * Format any thrown value into an error envelope suitable for CLI
+ * output. Recognises the SDK's `KindgiApiError` (typed wire error),
+ * plus the preview stub (`not-implemented-in-preview`), and falls back
+ * to raw `Error.message` for anything else.
+ */
+export function formatThrown(thrown, options) {
+    const wire = extractKindgiError(thrown);
+    if (wire !== null) {
+        if (wire.code === 'not-implemented-in-preview') {
+            const label = options.commandLabel.startsWith('kindgi ')
+                ? options.commandLabel
+                : `kindgi ${options.commandLabel}`;
+            return cliError(`Command '${label}' is not yet wired — SDK method '${wire.method}' is not available in this preview release.`, 2);
+        }
+        // Validation failures (AJV rejects on tool input, schema-validation-failed
+        // on body input) are useless without the `issues` array — the whole
+        // point of the error is "which field failed how". Promote those from
+        // --verbose-only to always-shown; every other error stays terse
+        // unless --verbose asks otherwise.
+        const detail = options.verbose
+            ? `\n${JSON.stringify(wire, null, 2)}`
+            : formatValidationDetail(wire);
+        return cliError(`Error [${wire.code}]: ${wire.message}${detail}`, 1);
+    }
+    if (thrown instanceof Error) {
+        const detail = options.verbose && thrown.stack ? `\n${thrown.stack}` : '';
+        return cliError(`Error: ${thrown.message}${detail}`, 1);
+    }
+    return cliError(`Error: ${String(thrown)}`, 1);
+}
+/**
+ * Format validation-issue detail inline (no --verbose required). We
+ * treat two error shapes as "validation":
+ *
+ *   - `code === 'server' && serverCode === 'tool-invocation-failed'`
+ *     with `fields.validationIssues` — AJV rejected the LLM's tool
+ *     arguments. Also emit the `receivedInput` truncated payload so
+ *     the author sees what the model actually sent.
+ *   - `code === 'invalid-request'` with `issues[]` — server-side
+ *     body validation. Emit each JSON-pointer + reason.
+ *
+ * Everything else returns `''` and stays on the terse one-liner.
+ */
+function formatValidationDetail(wire) {
+    if (wire.code === 'server' && wire.serverCode === 'tool-invocation-failed') {
+        const fields = wire.fields;
+        if (fields === undefined)
+            return '';
+        const issues = fields.validationIssues;
+        if (!Array.isArray(issues) || issues.length === 0)
+            return '';
+        const lines = [''];
+        for (const issue of issues) {
+            const path = typeof issue.instancePath === 'string' && issue.instancePath !== ''
+                ? issue.instancePath
+                : typeof issue.path === 'string'
+                    ? issue.path
+                    : '<root>';
+            const reason = typeof issue.message === 'string'
+                ? issue.message
+                : typeof issue.keyword === 'string'
+                    ? issue.keyword
+                    : JSON.stringify(issue);
+            lines.push(`  ✗ ${path}: ${reason}`);
+        }
+        if (fields.receivedInput !== undefined) {
+            lines.push(`  received: ${JSON.stringify(fields.receivedInput)}`);
+        }
+        return lines.join('\n');
+    }
+    if (wire.code === 'invalid-request' && wire.issues.length > 0) {
+        const lines = [''];
+        for (const issue of wire.issues) {
+            const path = issue.path === '' ? '<root>' : issue.path;
+            lines.push(`  ✗ ${path}: ${issue.message}`);
+        }
+        return lines.join('\n');
+    }
+    return '';
+}
+/**
+ * The SDK's `notImplementedInPreview()` currently returns a plain POJO
+ * (`{ code, message, method }`) that is `throw`n as-is — not wrapped
+ * in `KindgiApiError`. Recognise both shapes so callers see uniform
+ * error output.
+ */
+export function extractKindgiError(thrown) {
+    if (thrown instanceof KindgiApiError)
+        return thrown.error;
+    if (thrown !== null &&
+        typeof thrown === 'object' &&
+        'code' in thrown &&
+        typeof thrown.code === 'string' &&
+        'message' in thrown &&
+        typeof thrown.message === 'string') {
+        return thrown;
+    }
+    return null;
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/help.d.ts

@@ -0,0 +1,5 @@
+import type { Command } from './commands/types.js';
+export declare function rootHelpText(): string;
+/** `path`: the command's words from the root, so a group lists only its wired subcommands. */
+export declare function commandHelpText(command: Command, path?: readonly string[]): string;
+//# sourceMappingURL=help.d.ts.map

package/dist/help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAmB,MAAM,qBAAqB,CAAC;AAIpE,wBAAgB,YAAY,IAAI,MAAM,CAkBrC;AAED,8FAA8F;AAC9F,wBAAgB,eAAe,CAC7B,OAAO,EAAE,OAAO,EAChB,IAAI,GAAE,SAAS,MAAM,EAAmB,GACvC,MAAM,CAuBR"}