@eighty4/c2 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+## Unreleased
+
+- Evaluate env() and file() expressions in user data
+- Merge multiple user data into a MIME multipart message
+
+[Unreleased]: https://github.com/eighty4/c2/commits/main

package/LICENSE

@@ -0,0 +1,10 @@
+Copyright 2025 Adam McKee Bennett <adam.be.g84d@gmail.com>
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+

package/README.md

@@ -0,0 +1,79 @@
+# Cloud Config
+
+Blow up your `cloud-init` developer workflows!
+
+## Getting started
+
+`c2` publishes only TypeScript requiring Node >=23 to run.
+
+```shell
+npm i -g @eighty4/c2
+c2 -h
+```
+
+(tests use `bun:test` so [install Bun](https://bun.sh/docs/installation) for contributing!)
+
+## Using the CLI program
+
+```
+c2 ./cloud_init_dir
+
+# base64 encode your user data
+c2 --base64 ./cloud_init_dir
+```
+
+## Using the JS API
+
+```
+import { buildUserData } from '@eighty4/c2'
+
+const userData: string = await buildUserData('./cloud_init_dir')
+```
+
+## Cloud Config data dir
+
+Multiple user data are ordered by filenames and `01_` numbered prefixes help declaring execution order.
+
+```
+ls ./cloud_init_dir
+01_upgrades.yml
+02_security.yml
+03_services.sh
+```
+
+Shell scripts are supported as `x-shellscript` and YAML is included as `cloud-config` MIME types.
+
+## Evaluating expressions in user data
+
+Scripts and YAML support two template functions that can be used in expressions.
+
+### env()
+
+Replaces expression with content of a local environment variable.
+
+```bash
+#!/bin/sh
+
+ENV_VAR="${{ env('LOCAL_ENV_VAR') }}"
+```
+
+### file()
+
+Looks up a file from your local filesystem and replaces the expression with its content.
+
+```yaml
+#cloud-config
+
+users:
+    - name: devops-baller
+      ssh_authorized_keys:
+          - ${{ file('~/.ssh/my_ssh_key.pub') }}
+```
+
+Relative, absolute and `~/` paths are supported.
+
+## Contributing
+
+I use `c2` for initializing Debian cloud instances and locally test with QEMU and Ubuntu.
+
+Feedback on your use cases and worfklows is greatly appreciated!

package/c2.ts

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+import { buildUserData } from '#c2/build.ts'
+import { parseArgs, type ParsedArgs } from '#c2/cli.ts'
+import { doesDirExist } from '#c2/fs.ts'
+
+let args: ParsedArgs | undefined
+try {
+    args = parseArgs()
+} catch (e: any) {
+    if (e.message) {
+        console.error(e.message)
+    }
+}
+
+if (!args || args.help) {
+    const optional = (s: string) => `\u001b[90m${s}\u001b[0m`
+    const required = (s: string) => `\u001b[1m${s}\u001b[0m`
+    errorExit(
+        `c2 ${optional('[[--base64] | [--http PORT]]')} ${required('USER_DATA_DIR')}`,
+    )
+}
+
+if (args.httpPort) {
+    errorExit('--http PORT is not yet implemented')
+}
+
+if (!(await doesDirExist(args.userDataDir))) {
+    errorExit(`${args.userDataDir} directory does not exist`)
+}
+
+try {
+    const userData = await buildUserData(args.userDataDir)
+    console.log(args.base64 ? btoa(userData) : userData)
+} catch (e: any) {
+    errorExit(e.message)
+}
+
+function errorExit(msg: string): never {
+    console.error(msg)
+    process.exit(1)
+}

package/lib/attachments.ts

@@ -0,0 +1,49 @@
+import { readDirListing, readToString } from '#c2/fs.ts'
+
+export type AttachmentType = 'cloud-config' | 'x-shellscript'
+
+export interface Attachment {
+    path: string
+    content: string
+    filename: string
+    type: AttachmentType
+}
+
+export async function collectAttachments(
+    dir: string,
+): Promise<Array<Attachment>> {
+    const result: Array<Attachment> = []
+    for (const filename of await readDirListing(dir)) {
+        const path = `${dir}/${filename}`
+        const content = await readToString(path)
+        const type = resolveAttachmentType(filename, content)
+        result.push({ content, filename, path, type })
+    }
+    return result.sort(compareAttachmentFilenames)
+}
+
+function compareAttachmentFilenames(
+    a1: Attachment,
+    a2: Attachment,
+): 1 | 0 | -1 {
+    if (a1.filename === a2.filename) return 0
+    if (a1.filename > a2.filename) return 1
+    return -1
+}
+
+export function resolveAttachmentType(
+    filename: string,
+    content: string,
+): AttachmentType {
+    if (
+        filename.endsWith('.yml') ||
+        (filename.endsWith('.yaml') &&
+            content.trim().startsWith('#cloud-config'))
+    ) {
+        return 'cloud-config'
+    } else if (filename.endsWith('.sh')) {
+        return 'x-shellscript'
+    } else {
+        throw new Error(`unsupported file type ${filename}`)
+    }
+}

package/lib/build.ts

@@ -0,0 +1,59 @@
+import { type Attachment, collectAttachments } from '#c2/attachments.ts'
+import { evalTemplateExpressions } from '#c2/expression.ts'
+import { readToString } from '#c2/fs.ts'
+
+export type BuildUserDataOpts = {
+    attachmentBoundary?: string
+}
+
+export async function buildUserData(
+    userDataDir: string,
+    opts?: BuildUserDataOpts,
+): Promise<string> {
+    const attachments = await collectAttachments(userDataDir)
+    switch (attachments.length) {
+        case 0:
+            throw new Error(`nothing found in dir ${userDataDir}`)
+        case 1:
+            return evalTemplateExpressions(
+                await readToString(attachments[0].path),
+            )
+        default:
+            return buildMultipartUserData(attachments, opts?.attachmentBoundary)
+    }
+}
+
+function createBoundary(): string {
+    return new Date().toISOString()
+}
+
+async function buildMultipartUserData(
+    attachments: Array<Attachment>,
+    boundary: string = createBoundary(),
+): Promise<string> {
+    let result = `Content-Type: multipart/mixed; boundary=${boundary}
+MIME-Version: 1.0
+Number-Attachments: ${attachments.length}
+--${boundary}
+`
+
+    for (const attachment of attachments) {
+        let content: string
+        try {
+            content = await evalTemplateExpressions(attachment.content)
+        } catch (e: any) {
+            throw new Error(
+                `error templating ${attachment.filename}: ${e.message}`,
+            )
+        }
+        result += `Content-Type: text/${attachment.type}; charset="us-ascii"
+MIME-Version: 1.0
+Content-Transfer-Encoding: 7bit
+Content-Disposition: attachment; filename="${attachment.filename}"
+
+${content}
+--${boundary}
+`
+    }
+    return result
+}

package/lib/cli.ts

@@ -0,0 +1,48 @@
+export type ParsedArgs =
+    | { help: true }
+    | {
+          help?: false
+          base64?: boolean
+          httpPort?: number
+          userDataDir: string
+      }
+
+export function parseArgs(args?: Array<string>): ParsedArgs {
+    if (!args) {
+        args = process.argv
+    }
+    args = [...args]
+    while (!args.shift()!.endsWith('/c2.ts')) {}
+    let base64 = false
+    let httpPort: number | undefined
+    let userData: Array<string> = []
+    let expectHttpPort = false
+    for (const arg of args) {
+        if (expectHttpPort) {
+            expectHttpPort = false
+            httpPort = parseInt(arg, 10)
+            if (isNaN(httpPort)) {
+                throw new Error(`--http ${arg} is not a valid http port`)
+            }
+        } else if (arg === '-h' || arg === '--help') {
+            return { help: true }
+        } else if (arg === '--base64') {
+            base64 = true
+        } else if (arg === '--http') {
+            expectHttpPort = true
+        } else {
+            userData.push(arg)
+        }
+    }
+    switch (userData.length) {
+        case 1:
+            const userDataDir = userData[0]
+            if (typeof httpPort !== 'undefined') {
+                return { httpPort, userDataDir }
+            } else {
+                return { base64, userDataDir }
+            }
+        default:
+            throw new Error()
+    }
+}

package/lib/expression.ts

@@ -0,0 +1,65 @@
+import MagicString from 'magic-string'
+import { readToString } from '#c2/fs.ts'
+
+type TemplateExpression = {
+    index: number
+    innie: string
+    outie: string
+}
+
+export async function evalTemplateExpressions(
+    content: string,
+): Promise<string> {
+    const regex = new RegExp(/\${{\s*(.*)\s*}}/g)
+    let match: RegExpExecArray | null
+    const expressions: Array<TemplateExpression> = []
+    while ((match = regex.exec(content)) != null) {
+        expressions.push({
+            index: match.index,
+            innie: match[1],
+            outie: match[0],
+        })
+    }
+    if (!expressions.length) {
+        return content
+    }
+    const ms = new MagicString(content)
+    for (const expression of expressions) {
+        ms.update(
+            expression.index,
+            expression.index + expression.outie.length,
+            await evaluate(expression.innie),
+        )
+    }
+    return ms.toString()
+}
+
+async function evaluate(expression: string): Promise<string> {
+    let match: RegExpMatchArray | null
+    if ((match = expression.match(/env\(\s*'(.*)'\s*\)/)) != null) {
+        const envVarKey = match[1]
+        if (!/[A-Z_]+/.test(envVarKey)) {
+            throw new Error(
+                `env var expression \`${envVarKey}\` is not valid syntax`,
+            )
+        }
+        const envVarValue = process.env[envVarKey]
+        if (!envVarValue) {
+            throw new Error(`env var \`${envVarKey}\` does not exist`)
+        }
+        return envVarValue
+    } else if ((match = expression.match(/file\(\s*'(.*)'\s*\)/)) != null) {
+        let path = match[1]
+        if (path.startsWith('~/')) {
+            if (!process.env.HOME) {
+                throw new Error(
+                    `file \`${path}\` cannot be resolved without env var HOME`,
+                )
+            }
+            path = `${process.env.HOME}${path.substring(1)}`
+        }
+        return readToString(path)
+    }
+
+    throw new Error(`unsupported expression: ${expression}`)
+}

package/lib/fs.bun.ts

@@ -0,0 +1,5 @@
+export { doesDirExist, readDirListing } from '#c2/fs.node.ts'
+
+export async function readToString(p: string): Promise<string> {
+    return Bun.file(p).text()
+}

package/lib/fs.node.ts

@@ -0,0 +1,17 @@
+import { readdir, readFile, stat } from 'node:fs/promises'
+
+export async function doesDirExist(p: string): Promise<boolean> {
+    try {
+        return (await stat(p)).isDirectory()
+    } catch (ignore) {
+        return false
+    }
+}
+
+export async function readDirListing(p: string): Promise<Array<string>> {
+    return readdir(p)
+}
+
+export async function readToString(p: string): Promise<string> {
+    return readFile(p, 'utf8')
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@eighty4/c2",
+  "version": "0.0.1",
+  "author": "Adam McKee <adam.be.g84d@gmail.com>",
+  "repository": "https://github.com/eighty4/c2",
+  "homepage": "https://github.com/eighty4/c2",
+  "keywords": [
+    "devops",
+    "cloud init",
+    "cloud config",
+    "user data"
+  ],
+  "description": "Cross platform cloud config tooling for cloud-init",
+  "license": "BSD-2-Clause",
+  "type": "module",
+  "engines": {
+    "bun": ">=1.2",
+    "node": ">=23"
+  },
+  "main": "lib/build.ts",
+  "bin": {
+    "c2": "./c2.ts"
+  },
+  "scripts": {
+    "fmtcheck": "prettier --check .",
+    "typecheck": "tsc"
+  },
+  "imports": {
+    "#c2/fs.ts": {
+      "bun": "./lib/fs.bun.ts",
+      "node": "./lib/fs.node.ts"
+    },
+    "#c2/*": "./lib/*"
+  },
+  "dependencies": {
+    "magic-string": "0.30.17"
+  },
+  "devDependencies": {
+    "@types/bun": "1.2.5",
+    "@types/node": "^22.14.1",
+    "prettier": "^3.5.3",
+    "typescript": "5.8.2"
+  },
+  "files": [
+    "lib/**/*.ts",
+    "!lib/**/*.spec.ts",
+    "!lib/fs.testing.ts",
+    "CHANGELOG.md",
+    "c2.ts"
+  ]
+}