timonel 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Franklin García
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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
+AUTHORS OR COPYRIGHT HOLDERS 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.
+

package/README.md

@@ -0,0 +1,256 @@
+# Timonel
+
+[![License: MIT][license-badge]][license-url]
+[![npm version][npm-badge]][npm-url]
+[![Security][security-badge]][security-url]
+[![CodeQL][codeql-badge]][codeql-url]
+[![CI][ci-badge]][ci-url]
+[![pnpm][pnpm-badge]][pnpm-url]
+[![Node.js][node-badge]][node-url]
+[![TypeScript][ts-badge]][ts-url]
+[![Maintained by KenkoGeek][maintained-badge]][maintained-url]
+
+Timonel (Spanish for “helmsman”) is a TypeScript library to programmatically
+generate Helm charts using cdk8s. Define Kubernetes resources with classes and
+synthesize a full Helm chart with `Chart.yaml`, `values.yaml`, per‑environment
+values files, and `templates/`.
+
+Key features:
+
+- Type-safe API (strict TypeScript) with cdk8s constructs.
+- Helm templating helpers to embed `{{ .Values.* }}` where needed.
+- Simple multi-environment setup: `values.yaml`, `values-dev.yaml`, `values-prod.yaml`, etc.
+- Minimal CLI (`tl`) to scaffold an example and synthesize the chart.
+
+Advanced templating:
+
+- Programmatic Helm helpers: generate `templates/_helpers.tpl` and call helpers using `template()`/`include()`.
+
+## Installation
+
+### Using npm
+
+```bash
+npm install timonel
+```
+
+### Development setup
+
+Requirements: Node.js 20+ (Corepack enabled)
+
+```bash
+corepack enable
+corepack prepare pnpm@latest --activate
+pnpm install
+pnpm run build
+```
+
+### Developer setup (git hooks)
+
+After installing dependencies, enable git hooks with Husky:
+
+```bash
+pnpm dlx husky init || npx husky init
+```
+
+This sets up pre-commit and commit-msg hooks to run lint-staged and commitlint.
+The pre-commit hook also runs Node-based Markdown linting (markdownlint)
+automatically.
+
+Markdown commands:
+
+- Lint: `pnpm run md:lint`
+- Fix: `pnpm run md:fix`
+
+## Quick start
+
+<!-- markdownlint-disable MD029 -->
+
+1. Create an example project
+
+```bash
+tl init my-app-src
+```
+
+This generates `charts/my-app-src/chart.ts` with a working example.
+
+2. Synthesize Helm chart artifacts
+
+```bash
+tl synth charts/my-app-src charts/my-app/
+```
+
+Expected output:
+
+- `charts/my-app/Chart.yaml`
+- `charts/my-app/values.yaml`
+- `charts/my-app/values-dev.yaml`, `values-prod.yaml` (if defined)
+- `charts/my-app/templates/*.yaml`
+
+3. Use with Helm
+
+```bash
+helm template charts/my-app -f charts/my-app/values-dev.yaml
+helm install my-app charts/my-app -f charts/my-app/values-prod.yaml
+```
+
+Note: the output directory (`charts/my-app/` in this example) is overwritten if files
+exist. Use a clean folder or move old artifacts before running synth.
+
+### Package the chart (tgz)
+
+Requires Helm installed locally (`helm version`). Packages the chart directory into a
+`.tgz` that you can publish or attach to releases:
+
+```bash
+tl package charts/my-app charts/
+# or set HELM_BIN if helm is not in PATH
+HELM_BIN=/usr/local/bin/helm tl package charts/my-app charts/
+```
+
+## Library API
+
+```typescript
+import { ChartFactory } from 'timonel';
+import {
+  valuesRef,
+  helm,
+  template,
+  include,
+  numberRef,
+  boolRef,
+  stringRef,
+  floatRef,
+} from 'timonel/lib/helm';
+
+const factory = new ChartFactory({
+  meta: { name: 'my-app', version: '0.1.0', appVersion: '1.0.0' },
+  defaultValues: {
+    image: { repository: 'nginx', tag: '1.27' },
+    replicas: 2,
+    service: { port: 80 },
+  },
+  envValues: { dev: { replicas: 1 }, prod: { replicas: 4 } },
+  helpersTpl: [
+    {
+      name: 'timonel.fullname',
+      body: `{{- printf "%s-%s" .Chart.Name .Release.Name | trunc 63 | trimSuffix "-" -}}`,
+    },
+  ],
+});
+
+factory.addDeployment({
+  name: 'my-app',
+  image: `${valuesRef('image.repository')}:${valuesRef('image.tag')}`,
+  replicas: numberRef('replicas') as any,
+  containerPort: 80,
+});
+
+factory.addService({ name: 'my-app', port: numberRef('service.port') as any });
+
+// Use a named helper in annotations (example)
+factory.addDeployment({
+  name: 'annotated',
+  image: 'nginx',
+  containerPort: 80,
+  env: {
+    FULLNAME: include('timonel.fullname'),
+  },
+});
+
+factory.write('dist/charts/my-app');
+```
+
+- `valuesRef(path)`: returns a Helm placeholder string for `.Values.*`.
+- You can pass these strings directly into cdk8s constructs; they are preserved in the YAML.
+- `template(name, ctx='.')` and `include(name, ctx='.')`: inject calls to helpers defined in `_helpers.tpl`.
+- `numberRef(path)`, `boolRef(path)`: cast `.Values.*` to numeric/boolean using Sprig
+  (`int`, `toBool`). Use `as any` where constructs expect typed numbers/bools.
+- `stringRef(path)`, `floatRef(path)`: cast `.Values.*` to string/float using Sprig
+  (`toString`, `float64`).
+
+## Multi-environment values
+
+Provide `envValues` in the `ChartFactory` constructor to automatically create
+`values-<env>.yaml` files. Each environment file overrides defaults from
+`values.yaml`.
+
+## Security
+
+- ESLint security plugin with comprehensive vulnerability detection
+- Automated dependency scanning via Dependabot
+- Security audit in CI/CD pipeline
+- Provenance-enabled npm publishing
+- CodeQL analysis for code security
+
+## Notes on cdk8s and Helm templates
+
+- cdk8s synthesizes Kubernetes manifests. Timonel wraps them into a Helm chart
+  structure and allows Helm placeholders to appear in string fields (e.g.,
+  `{{ .Values.image.tag }}`).
+- For advanced templating, Timonel can generate `_helpers.tpl`. Provide `helpersTpl`
+  in `ChartFactory` as a string (verbatim) or as named helpers. Use `template()` or `include()`
+  to reference them in your manifests.
+
+## Roadmap
+
+- Helpers for common patterns (HPA, auto-scaling)
+- Richer CLI (resource generators, diff)
+- Enhanced multi-cloud support
+- Template validation and testing utilities
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/amazing-feature`
+3. Make your changes following the existing code style
+4. Run tests: `pnpm run lint && pnpm run build`
+5. Commit using conventional commits: `git commit -m 'feat: add amazing feature'`
+6. Push to the branch: `git push origin feature/amazing-feature`
+7. Open a Pull Request
+
+## Troubleshooting
+
+### Common Issues
+
+#### Error: chart.ts not found
+
+- Ensure you're running `tl synth` from the correct directory
+- Verify the chart.ts file exists in the specified path
+
+#### TypeScript compilation errors
+
+- Check Node.js version (requires 20+)
+- Run `pnpm install` to ensure dependencies are installed
+- Verify TypeScript configuration in tsconfig.json
+
+#### Helm template errors
+
+- Validate YAML syntax in generated templates
+- Check Helm values references match your values.yaml structure
+- Use `helm template --debug` for detailed error information
+
+## License
+
+MIT
+
+<!-- Badges section -->
+
+[license-badge]: https://img.shields.io/badge/License-MIT-yellow.svg
+[license-url]: https://opensource.org/licenses/MIT
+[npm-badge]: https://img.shields.io/npm/v/timonel.svg
+[npm-url]: https://www.npmjs.com/package/timonel
+[security-badge]: https://img.shields.io/badge/Security-Policy-2ea44f?logo=security&logoColor=fff
+[security-url]: SECURITY.md
+[pnpm-badge]: https://img.shields.io/badge/pm-pnpm-ffd95a?logo=pnpm&logoColor=fff&labelColor=24292e
+[pnpm-url]: https://pnpm.io/
+[node-badge]: https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js&logoColor=fff
+[node-url]: https://nodejs.org/
+[ts-badge]: https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=fff
+[ts-url]: https://www.typescriptlang.org/
+[maintained-badge]: https://img.shields.io/badge/maintained%20by-KenkoGeek-6C78AF?style=flat
+[maintained-url]: https://github.com/kenkogeek/
+[ci-badge]: https://github.com/KenkoGeek/timonel/actions/workflows/ci.yml/badge.svg?branch=main
+[ci-url]: https://github.com/KenkoGeek/timonel/actions/workflows/ci.yml
+[codeql-badge]: https://github.com/KenkoGeek/timonel/actions/workflows/codeql.yml/badge.svg
+[codeql-url]: https://github.com/KenkoGeek/timonel/actions/workflows/codeql.yml

package/SECURITY.md

@@ -0,0 +1,44 @@
+# Security Policy
+
+## Reporting Security Vulnerabilities
+
+- **DO NOT** create public GitHub issues for security vulnerabilities
+- Report vulnerabilities privately via project maintainers or GitHub Security Advisories
+- Include detailed information about the vulnerability and steps to reproduce
+- We aim to triage within 5 business days and provide updates within 10 business days
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.1.x   | :white_check_mark: |
+
+## Development Security
+
+### Static Analysis
+
+- TypeScript strict mode enabled with comprehensive compiler checks
+- ESLint with security plugin (`eslint-plugin-security`) in CI/CD
+- SonarJS plugin for code quality and security analysis
+- Automated dependency vulnerability scanning via `pnpm audit`
+
+### Dependencies
+
+- Regular dependency updates via Dependabot
+- Security-focused dependency management
+- No runtime network calls in library APIs
+- Minimal dependency footprint
+
+### CI/CD Security
+
+- GitHub Actions with minimal permissions
+- Dependency caching with integrity checks
+- Automated security audits on every build
+- CodeQL analysis for vulnerability detection
+
+### Best Practices
+
+- Input validation and sanitization
+- Secure coding practices following OWASP guidelines
+- Regular security reviews of code changes
+- Principle of least privilege in all configurations

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}