@rip-lang/stamp 0.1.1

package/README.md

@@ -0,0 +1,166 @@
+<img src="https://raw.githubusercontent.com/shreeve/rip-lang/main/docs/assets/rip.png" style="width:50px" /> <br>
+
+# Stamp - @rip-lang/stamp
+
+**Declarative host provisioning — no state file, no agent, no YAML.**
+
+Stamp reads a Stampfile, resolves each directive to a handler, and reconciles
+the declared state against reality using three operations: **check**, **apply**,
+and **verify**.
+
+```
+stamp apply Hostfile
+```
+
+---
+
+## Quick Start
+
+```bash
+# Preview changes (read-only)
+stamp plan Hostfile
+
+# Apply the declared state
+stamp apply Hostfile
+
+# Audit current state
+stamp verify Hostfile
+```
+
+## Stampfile Syntax
+
+A Stampfile declares the desired state of a system. Each top-level entry
+names a resource using a **directive**. Indented lines below it describe
+properties.
+
+```
+packages curl git jq zfsutils-linux
+
+pool tank /dev/sdb
+  compression zstd
+  atime off
+
+container web ubuntu/24.04
+  profile trusted
+  disk data /tank/web -> /data
+  start
+
+firewall
+  default deny incoming
+  default allow outgoing
+  allow ssh
+  allow 443/tcp
+```
+
+### Three levels of expression
+
+- **Inline** — single line: `packages curl git jq`
+- **Block** — directive + indented properties
+- **Expanded** — property with its own nested sub-block
+
+### Variables
+
+```
+set POOL   tank
+set DEVICE /dev/sdb
+
+pool $POOL $DEVICE
+```
+
+### The `->` operator
+
+Source-to-destination mapping:
+
+```
+disk data /tank/web -> /data
+disk logs /tank/logs -> /var/log readonly
+```
+
+### Grouped directives
+
+Plural forms expand to individual directives:
+
+```
+datasets
+  tank/home
+  tank/shared
+    owner 1001:1001
+    mode 2775
+```
+
+## Built-in Directives
+
+| Directive | Purpose |
+|-----------|---------|
+| `brew` | Homebrew packages (macOS) |
+| `packages` | System packages (apt-get) |
+| `pool` | ZFS pool creation |
+| `dataset` | ZFS dataset with ownership/permissions |
+| `profile` | Incus profile configuration |
+| `container` | Incus container management |
+| `incus` | Incus daemon initialization |
+| `multipass` | Multipass virtual machines |
+| `user` | System user management |
+| `group` | System group management |
+| `firewall` | ufw firewall rules |
+| `ssh` | SSH daemon configuration |
+| `service` | systemd service management |
+
+## Handler Contract
+
+Every directive handler exports three async functions:
+
+- **check(name, props)** — returns `"ok"`, `"drift"`, or `"missing"`
+- **apply(name, props)** — make reality match the declaration
+- **verify(name, props)** — return `[{ status, message }]` results
+
+## Plugin System
+
+Handlers resolve in this order:
+
+1. Built-in (`directives/`)
+2. Local (`./directives/` beside Stampfile)
+3. Installed (`~/.stamp/directives/`)
+4. npm (`@stamp/<name>` or `stamp-<name>`)
+5. Remote (via `use` directive)
+
+### Writing a directive
+
+```coffee
+import { sh, ok, run } from "@rip-lang/stamp/helpers"
+
+export name        = "mydirective"
+export description = "What it does"
+
+export check = (name, props) ->
+  return 'missing' unless ok "some-check"
+  'ok'
+
+export apply = (name, props) ->
+  sh "some-command"
+
+export verify = (name, props) ->
+  [{ status: 'pass', message: 'looks good' }]
+```
+
+## CLI
+
+```
+stamp apply [file]           Reconcile system to match Stampfile
+stamp verify [file]          Check current state, report PASS/WARN/FAIL
+stamp plan [file]            Dry-run: show what apply would do
+stamp list                   Show all available directives
+stamp info <directive>       Show a directive's syntax and properties
+stamp version                Print version
+stamp help                   Show help
+```
+
+Default file search: `Stampfile`, `Hostfile`, `Containerfile`.
+
+## Runtime
+
+Bun + Rip. Zero dependencies beyond `rip-lang`.
+
+## License
+
+MIT

package/bin/stamp

@@ -0,0 +1,21 @@
+#!/usr/bin/env bun
+
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const loaderPath = join(__dirname, '..', '..', '..', 'rip-loader.js');
+
+// Preload the Rip loader so .rip imports work
+const { spawnSync } = await import('child_process');
+
+const result = spawnSync('bun', [
+  '--preload', loaderPath,
+  join(__dirname, '..', 'src', 'cli.rip'),
+  ...process.argv.slice(2)
+], {
+  stdio: 'inherit',
+  env: { ...process.env, NODE_PATH: join(__dirname, '..', '..', '..') }
+});
+
+process.exit(result.status || 0);

package/directives/brew.rip

@@ -0,0 +1,48 @@
+export name        = "brew"
+export description = "Ensures Homebrew packages are installed (macOS)"
+export positional  = []
+
+gather = (name, props) ->
+  list = [...(props.args or [])]
+  for own k, entries of props when k != 'args'
+    list.push k
+    for entry in entries
+      list.push ...entry.args if entry.args?.length
+  list
+
+installed = (pkg) ->
+  ok $"brew list #{pkg}"
+
+export check = (name, props) ->
+  return 'missing' unless ok $"which brew"
+  list = gather name, props
+  return 'ok' if list.length == 0
+  for pkg in list
+    return 'drift' unless installed pkg
+  'ok'
+
+export apply = (name, props) ->
+  unless ok $"which brew"
+    sh "/bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\""
+
+  list = gather name, props
+  return if list.length == 0
+  missing = (pkg for pkg in list when not installed pkg)
+  return if missing.length == 0
+  for pkg in missing
+    sh $"brew install #{pkg}"
+
+export verify = (name, props) ->
+  results = []
+  unless ok $"which brew"
+    results.push { status: 'fail', message: "homebrew not installed" }
+    return results
+  results.push { status: 'pass', message: "homebrew installed" }
+
+  list = gather name, props
+  for pkg in list
+    if installed pkg
+      results.push { status: 'pass', message: "#{pkg} installed" }
+    else
+      results.push { status: 'fail', message: "#{pkg} not installed" }
+  results

package/directives/container.rip

@@ -0,0 +1,106 @@
+export name        = "container"
+export description = "Manages Incus containers"
+export positional  = ["name", "image"]
+export properties  =
+  profile: { description: "Attach an Incus profile", multi: true }
+  disk:    { description: "Mount a host path into the container", arrow: true, multi: true }
+  user:    { description: "Create a user inside the container", multi: true }
+  start:   { description: "Ensure container is running" }
+
+isRunning = (name) ->
+  out = run $"incus info #{name}"
+  out.ok and out.stdout.toLowerCase().includes 'status: running'
+
+export check = (name, props) ->
+  return 'missing' unless ok $"incus info #{name}"
+
+  if props.profile
+    current = sh $"incus config show #{name}"
+    for entry in props.profile
+      return 'drift' unless current.includes entry.args[0]
+
+  if props.disk
+    for entry in props.disk
+      return 'drift' unless ok $"incus config device get #{name} #{entry.args[0]} source"
+
+  return 'drift' if props.start and not isRunning name
+
+  'ok'
+
+export apply = (name, props) ->
+  image = props.args?[0]
+
+  unless ok $"incus info #{name}"
+    raise "container '#{name}' requires an image argument" unless image
+    sh $"incus init #{image} #{name}"
+
+  if props.profile
+    current = sh $"incus config show #{name}"
+    for entry in props.profile
+      sh $"incus profile add #{name} #{entry.args[0]}" unless current.includes entry.args[0]
+
+  if props.disk
+    for entry in props.disk
+      devname = entry.args[0]
+      unless ok $"incus config device get #{name} #{devname} source"
+        ro = 'readonly=true' if 'readonly' in (entry.flags or [])
+        sh $"incus config device add #{name} #{devname} disk source=#{entry.source} path=#{entry.dest} #{ro}"
+
+  if props.start and not isRunning name
+    sh $"incus start #{name}"
+
+    attempts = 30
+    while attempts > 0
+      break if ok $"incus exec #{name} -- true"
+      Bun.sleepSync 1000
+      attempts--
+    raise "Container #{name} not ready after 30 seconds" if attempts == 0
+
+  if props.user and isRunning name
+    for entry in props.user
+      username = entry.args[0]
+      uidgid   = entry.args[1]
+      unless ok $"incus exec #{name} -- id #{username}"
+        [uid, gid] = uidgid.split ':'
+        ok $"incus exec #{name} -- groupadd -g #{gid} #{username}" unless ok $"incus exec #{name} -- getent group #{gid}"
+        sh $"incus exec #{name} -- useradd -m -u #{uid} -g #{gid} #{username}"
+
+export verify = (name, props) ->
+  results = []
+
+  unless ok $"incus info #{name}"
+    results.push { status: 'fail', message: "container #{name} missing" }
+    return results
+  results.push { status: 'pass', message: "container #{name} exists" }
+
+  if isRunning name
+    results.push { status: 'pass', message: "#{name} running" }
+  else
+    results.push { status: 'fail', message: "#{name} not running" }
+
+  if props.profile
+    current = sh $"incus config show #{name}"
+    for entry in props.profile
+      want = entry.args[0]
+      if current.includes want
+        results.push { status: 'pass', message: "#{name} profile #{want} attached" }
+      else
+        results.push { status: 'fail', message: "#{name} profile #{want} not attached" }
+
+  if props.disk
+    for entry in props.disk
+      devname = entry.args[0]
+      if ok $"incus config device get #{name} #{devname} source"
+        results.push { status: 'pass', message: "#{name} disk #{devname} present" }
+      else
+        results.push { status: 'fail', message: "#{name} disk #{devname} missing" }
+
+  if props.user and isRunning name
+    for entry in props.user
+      username = entry.args[0]
+      if ok $"incus exec #{name} -- id #{username}"
+        results.push { status: 'pass', message: "#{name} user #{username} exists" }
+      else
+        results.push { status: 'fail', message: "#{name} user #{username} missing" }
+
+  results

package/directives/dataset.rip

@@ -0,0 +1,40 @@
+export name        = "dataset"
+export description = "Ensures a ZFS dataset exists with correct ownership and permissions"
+export positional  = ["path"]
+export properties  =
+  owner: { description: "Ownership as uid:gid" }
+  mode:  { description: "Permission mode (octal)" }
+
+export check = (path, props) ->
+  return 'missing' unless ok $"zfs list #{path}"
+  mountpoint = sh $"zfs get -H -o value mountpoint #{path}"
+  if want = props.owner?[0]?.args?[0]
+    return 'drift' if want isnt sh $"stat -c %u:%g #{mountpoint}"
+  if want = props.mode?[0]?.args?[0]
+    return 'drift' if want isnt sh $"stat -c %a #{mountpoint}"
+  'ok'
+
+export apply = (path, props) ->
+  sh $"zfs create #{path}" unless ok $"zfs list #{path}"
+  mountpoint = sh $"zfs get -H -o value mountpoint #{path}"
+  sh $"chown #{props.owner[0].args[0]} #{mountpoint}" if props.owner
+  sh $"chmod #{props.mode[0].args[0]} #{mountpoint}" if props.mode
+
+export verify = (path, props) ->
+  results = []
+  unless ok $"zfs list #{path}"
+    results.push { status: 'fail', message: "dataset missing: #{path}" }
+    return results
+  results.push { status: 'pass', message: "dataset exists: #{path}" }
+  mountpoint = sh $"zfs get -H -o value mountpoint #{path}"
+  if want = props.owner?[0]?.args?[0]
+    if want is (have = sh $"stat -c %u:%g #{mountpoint}")
+      results.push { status: 'pass', message: "#{path} owner is #{want}" }
+    else
+      results.push { status: 'fail', message: "#{path} owner is #{have}, expected #{want}" }
+  if want = props.mode?[0]?.args?[0]
+    if want is (have = sh $"stat -c %a #{mountpoint}")
+      results.push { status: 'pass', message: "#{path} mode is #{want}" }
+    else
+      results.push { status: 'fail', message: "#{path} mode is #{have}, expected #{want}" }
+  results

package/directives/firewall.rip

@@ -0,0 +1,78 @@
+export name        = "firewall"
+export description = "Ensures ufw firewall rules are configured"
+export positional  = []
+export properties  =
+  default: { description: "Default policy: deny/allow incoming/outgoing", multi: true }
+  allow:   { description: "Allow rule", multi: true }
+  deny:    { description: "Deny rule", multi: true }
+
+ufwActive = ->
+  out = run $"ufw status"
+  out.ok and out.stdout.includes 'Status: active'
+
+export check = (name, props) ->
+  return 'missing' unless ok $"which ufw"
+  return 'drift'   unless ufwActive()
+
+  if props.default
+    status = sh $"ufw status verbose"
+    for entry in props.default
+      [action, direction] = entry.args
+      return 'drift' unless status.includes action
+
+  if props.allow
+    status = sh $"ufw status"
+    for entry in props.allow
+      rule = entry.args.join ' '
+      return 'drift' unless status.toUpperCase().includes rule.toUpperCase()
+
+  'ok'
+
+export apply = (name, props) ->
+  unless ok $"which ufw"
+    sh $"apt-get update -qq"
+    sh $"apt-get install -y -qq ufw"
+
+  if props.default
+    for entry in props.default
+      [action, direction] = entry.args
+      sh $"ufw default #{action} #{direction}"
+
+  if props.allow
+    for entry in props.allow
+      sh $"ufw allow #{entry.args.join ' '}"
+
+  if props.deny
+    for entry in props.deny
+      sh $"ufw deny #{entry.args.join ' '}"
+
+  unless ufwActive()
+    sh $"ufw --force enable"
+
+export verify = (name, props) ->
+  results = []
+
+  unless ok $"which ufw"
+    results.push { status: 'fail', message: "ufw not installed" }
+    return results
+
+  if ufwActive()
+    results.push { status: 'pass', message: "ufw active" }
+  else
+    results.push { status: 'fail', message: "ufw not active" }
+
+  if props.default
+    status = sh $"ufw status verbose"
+    for entry in props.default
+      [action, direction] = entry.args
+      if status.includes action
+        results.push { status: 'pass', message: "default #{action} #{direction}" }
+      else
+        results.push { status: 'fail', message: "default #{action} #{direction} not set" }
+
+  if props.allow
+    for entry in props.allow
+      rule = entry.args.join ' '
+      results.push { status: 'pass', message: "allow #{rule}" }
+
+  results

package/directives/group.rip

@@ -0,0 +1,34 @@
+export name        = "group"
+export description = "Ensures a system group exists on the host"
+export positional  = ["name", "gid"]
+
+export check = (name, props) ->
+  return 'missing' unless ok $"getent group #{name}"
+
+  if want = props.args?[0]
+    return 'drift' if want isnt (sh $"getent group #{name}").split(':')[2]
+
+  'ok'
+
+export apply = (name, props) ->
+  gid = props.args?[0]
+  unless ok $"getent group #{name}"
+    if gid
+      sh $"groupadd -g #{gid} #{name}"
+    else
+      sh $"groupadd #{name}"
+
+export verify = (name, props) ->
+  results = []
+  unless ok $"getent group #{name}"
+    results.push { status: 'fail', message: "group #{name} missing" }
+    return results
+  results.push { status: 'pass', message: "group #{name} exists" }
+
+  if want = props.args?[0]
+    if want is (have = (sh $"getent group #{name}").split(':')[2])
+      results.push { status: 'pass', message: "#{name} gid is #{want}" }
+    else
+      results.push { status: 'fail', message: "#{name} gid is #{have}, expected #{want}" }
+
+  results

package/directives/incus.rip

@@ -0,0 +1,111 @@
+export name        = "incus"
+export description = "Ensures the Incus daemon is initialized with network and storage"
+export positional  = []
+export properties  =
+  storage: { description: "Storage pool: <name> <driver> <source>" }
+  network: { description: "Network bridge name" }
+
+export check = (name, props) ->
+  return 'missing' unless ok $"incus info"
+
+  if props.storage
+    poolName = props.storage[0].args[0]
+    return 'drift' unless ok $"incus storage show #{poolName}"
+
+  if props.network
+    bridge = props.network[0].args[0]
+    return 'drift' unless ok $"incus network show #{bridge}"
+
+  'ok'
+
+export apply = (name, props) ->
+  unless ok $"systemctl is-active incus"
+    sh $"systemctl enable --now incus"
+
+  unless ok $"incus info"
+    storageEntry = props.storage?[0]
+    networkEntry = props.network?[0]
+
+    networkYaml = if networkEntry
+      bridge = networkEntry.args[0]
+      """
+      networks:
+      - config:
+          ipv4.address: auto
+          ipv4.nat: "true"
+          ipv6.address: none
+        description: ""
+        name: #{bridge}
+        type: bridge
+      """
+    else
+      "networks: []"
+
+    storageYaml = if storageEntry
+      [poolName, driver, source] = storageEntry.args
+      """
+      storage_pools:
+      - config:
+          source: #{source}
+        description: ""
+        driver: #{driver}
+        name: #{poolName}
+      """
+    else
+      "storage_pools: []"
+
+    defaultPool = storageEntry?.args?[0] or 'default'
+
+    preseed = """
+      config: {}
+      #{networkYaml}
+      #{storageYaml}
+      profiles:
+      - config: {}
+        description: Default Incus profile
+        devices:
+          root:
+            path: /
+            pool: #{defaultPool}
+            type: disk
+        name: default
+      """
+
+    out = Bun.spawnSync ['incus', 'admin', 'init', '--preseed'], { stdin: Buffer.from(preseed), stdout: 'pipe', stderr: 'pipe' }
+    unless out.exitCode == 0
+      raise "incus admin init failed: #{out.stderr.toString().trim()}"
+  else
+    if props.storage
+      poolName = props.storage[0].args[0]
+      unless ok $"incus storage show #{poolName}"
+        raise "Incus already initialized but storage pool '#{poolName}' does not exist"
+
+    if props.network
+      bridge = props.network[0].args[0]
+      unless ok $"incus network show #{bridge}"
+        raise "Incus already initialized but network '#{bridge}' does not exist"
+
+export verify = (name, props) ->
+  results = []
+
+  if ok $"incus info"
+    results.push { status: 'pass', message: "incus daemon running" }
+  else
+    results.push { status: 'fail', message: "incus daemon not running" }
+    return results
+
+  if props.storage
+    poolName = props.storage[0].args[0]
+    if ok $"incus storage show #{poolName}"
+      results.push { status: 'pass', message: "storage pool #{poolName} exists" }
+    else
+      results.push { status: 'fail', message: "storage pool #{poolName} missing" }
+
+  if props.network
+    bridge = props.network[0].args[0]
+    if ok $"incus network show #{bridge}"
+      results.push { status: 'pass', message: "network #{bridge} exists" }
+    else
+      results.push { status: 'fail', message: "network #{bridge} missing" }
+
+  results

package/directives/multipass.rip

@@ -0,0 +1,47 @@
+export name        = "multipass"
+export description = "Manages Multipass virtual machines"
+export positional  = ["name", "image"]
+export properties  =
+  cpus:   { description: "Number of CPUs (default: 1)" }
+  memory: { description: "Memory allocation (default: 1G)" }
+  disk:   { description: "Disk size (default: 5G)" }
+  start:  { description: "Ensure VM is running" }
+
+isRunning = (name) ->
+  out = run $"multipass info #{name}"
+  out.ok and out.stdout.includes 'State:' and out.stdout.includes 'Running'
+
+export check = (name, props) ->
+  return 'missing' unless ok $"multipass info #{name}"
+  return 'drift' if props.start and not isRunning name
+  'ok'
+
+export apply = (name, props) ->
+  image = props.args?[0] or '24.04'
+
+  unless ok $"multipass info #{name}"
+    cpus   = props.cpus?[0]?.args?[0]
+    memory = props.memory?[0]?.args?[0]
+    disk   = props.disk?[0]?.args?[0]
+    sh ['multipass', 'launch', image, '--name', name,
+      '--cpus',   cpus   or '1',
+      '--memory', memory or '1G',
+      '--disk',   disk   or '5G']
+
+  if props.start and not isRunning name
+    sh $"multipass start #{name}"
+
+export verify = (name, props) ->
+  results = []
+
+  unless ok $"multipass info #{name}"
+    results.push { status: 'fail', message: "vm #{name} missing" }
+    return results
+  results.push { status: 'pass', message: "vm #{name} exists" }
+
+  if isRunning name
+    results.push { status: 'pass', message: "#{name} running" }
+  else
+    results.push { status: 'fail', message: "#{name} not running" }
+
+  results

package/directives/packages.rip

@@ -0,0 +1,40 @@
+export name        = "packages"
+export description = "Ensures system packages are installed"
+export positional  = []
+
+gather = (name, props) ->
+  list = [...(props.args or [])]
+  for own k, entries of props when k != 'args'
+    list.push k
+    for entry in entries
+      list.push ...entry.args if entry.args?.length
+  list
+
+installed = (pkg) ->
+  out = run $"dpkg -s #{pkg}"
+  out.ok and out.stdout.includes 'Status: install ok installed'
+
+export check = (name, props) ->
+  list = gather name, props
+  return 'ok' if list.length == 0
+  for pkg in list
+    return 'drift' unless installed pkg
+  'ok'
+
+export apply = (name, props) ->
+  list = gather name, props
+  return if list.length == 0
+  missing = (pkg for pkg in list when not installed pkg)
+  return if missing.length == 0
+  sh $"apt-get update -qq"
+  sh ['apt-get', 'install', '-y', '-qq', ...missing]
+
+export verify = (name, props) ->
+  list = gather name, props
+  results = []
+  for pkg in list
+    if installed pkg
+      results.push { status: 'pass', message: "#{pkg} installed" }
+    else
+      results.push { status: 'fail', message: "#{pkg} not installed" }
+  results