k9-writer.lua

-- SPDX-License-Identifier: MIT
-- Copyright (c) 2026 Jonathan D.A. Jewell
--
-- k9-writer.lua — Pandoc custom writer for K9 (Self-Validating Components)
--
-- Converts Pandoc's internal AST to K9 Nickel format (.k9.ncl).
-- Produces valid Nickel configuration with the K9 schema structure:
--   - Pedigree metadata (name, version, description, author)
--   - Security level (Kennel/Yard/Hunt) with permission flags
--   - Target platform configuration
--   - Recipes (install, validate, deploy, migrate)
--   - Configuration records
--
-- Usage:
--   pandoc input.md -t k9-writer.lua -o component.k9.ncl
--   pandoc input.html -t k9-writer.lua
--   pandoc input.json -t k9-writer.lua -o config.k9.ncl
--
-- Round-trip: pandoc -f k9.lua input.k9.ncl -t k9-writer.lua -o roundtrip.k9.ncl
--
-- Media type: application/vnd.k9+nickel (IANA registration pending)
-- Spec: /standards/k9-svc/SPEC.adoc

--- Writer entry point. Pandoc calls this with the full document AST.
--- Returns a string containing the K9 Nickel output.
function Writer(doc, opts)
  local buffer = {}
  local function add(s) table.insert(buffer, s) end

  -- SPDX header
  add("# SPDX-License-Identifier: PMPL-1.0-or-later")

  -- Extract metadata from the document
  local meta = doc.meta or {}
  local title = meta_string(meta, "title") or "untitled"
  local version = meta_string(meta, "version") or "0.1.0"
  local security = meta_string(meta, "k9-security-level") or "Kennel"
  local spdx = meta_string(meta, "spdx-license") or "PMPL-1.0-or-later"

  add("")

  -- Track which sections we've seen to build the K9 structure
  local current_section = nil
  local sections = {}
  local pedigree = {}
  local recipes = {}
  local config_entries = {}

  -- Walk the document blocks and extract structured data
  for _, block in ipairs(doc.blocks) do
    if block.t == "Header" then
      current_section = render_inlines(block.content):lower():gsub("%s+", "_")

    elseif block.t == "BulletList" and current_section then
      -- Extract key-value pairs from bullet lists
      for _, item in ipairs(block.content) do
        local text = ""
        for _, b in ipairs(item) do
          text = text .. render_block_inline(b)
        end
        local key, value = text:match("^%*%*(.-)%*%*:%s*(.+)$")
        if key and value then
          if current_section:match("pedigree") or current_section:match("metadata") then
            pedigree[key:lower()] = value
          elseif current_section:match("security") then
            config_entries[key:lower():gsub("%s+", "_")] = value
          end
        end
      end

    elseif block.t == "CodeBlock" and current_section then
      -- Recipe code blocks
      if current_section:match("recipe") or current_section:match("install") or
         current_section:match("validate") or current_section:match("deploy") then
        local recipe_name = current_section:gsub("recipes?_?", ""):gsub("^_", "")
        if recipe_name == "" then recipe_name = "validate" end
        recipes[recipe_name] = block.text
      end

    elseif block.t == "DefinitionList" then
      -- K9 definition lists become record fields
      for _, item in ipairs(block.content) do
        local term = item[1]
        local defs = item[2]
        local key = render_inlines(term):match("`(.-)`") or render_inlines(term)
        local value = ""
        if defs and #defs > 0 and #defs[1] > 0 then
          value = render_block_inline(defs[1][1])
        end
        if key and key ~= "" then
          config_entries[key] = value
        end
      end
    end
  end

  -- Generate K9 Nickel output
  add("")
  add("# K9 Self-Validating Component")
  add("# Generated by k9-writer.lua (Pandoc custom writer)")
  add("")

  -- Pedigree block
  add("let pedigree = {")
  add('  name = "' .. escape_nickel(pedigree["name"] or title) .. '",')
  add('  version = "' .. escape_nickel(pedigree["version"] or version) .. '",')
  if pedigree["description"] then
    add('  description = "' .. escape_nickel(pedigree["description"]) .. '",')
  end
  if pedigree["author"] then
    add('  author = "' .. escape_nickel(pedigree["author"]) .. '",')
  end
  add('  spdx_license = "' .. escape_nickel(spdx) .. '",')
  add("} in")
  add("")

  -- Security block
  add("let security = {")
  add("  trust_level = '" .. security .. ",")

  -- Permission flags based on security level
  if security == "Hunt" then
    add("  allow_network = true,")
    add("  allow_filesystem_write = true,")
    add("  allow_subprocess = true,")
  elseif security == "Yard" then
    add("  allow_network = false,")
    add("  allow_filesystem_write = false,")
    add("  allow_subprocess = false,")
  else -- Kennel
    add("  allow_network = false,")
    add("  allow_filesystem_write = false,")
    add("  allow_subprocess = false,")
  end
  add("} in")
  add("")

  -- Recipes block (if any)
  if next(recipes) then
    add("let recipes = {")
    for recipe_name, recipe_cmd in pairs(recipes) do
      -- Use multiline string for shell scripts
      if recipe_cmd:find("\n") then
        add("  " .. recipe_name .. ' = m%"')
        for line in recipe_cmd:gmatch("([^\n]*)\n?") do
          if line ~= "" then
            add("    " .. line)
          end
        end
        add('  "%,')
      else
        add("  " .. recipe_name .. ' = "' .. escape_nickel(recipe_cmd) .. '",')
      end
    end
    add("} in")
    add("")
  end

  -- Configuration entries (if any beyond pedigree/security)
  if next(config_entries) then
    add("let config = {")
    for key, value in pairs(config_entries) do
      -- Skip entries already in pedigree or security
      if not pedigree[key] and key ~= "trust_level" and
         not key:match("allow_") then
        if value == "true" or value == "false" then
          add("  " .. key .. " = " .. value .. ",")
        elseif tonumber(value) then
          add("  " .. key .. " = " .. value .. ",")
        else
          add('  ' .. key .. ' = "' .. escape_nickel(value) .. '",')
        end
      end
    end
    add("} in")
    add("")
  end

  -- Export block
  add("{")
  add("  pedigree,")
  add("  security,")
  if next(recipes) then add("  recipes,") end
  if next(config_entries) then add("  config,") end
  add("}")
  add("")

  return table.concat(buffer, "\n")
end

--- Extract a string value from Pandoc metadata.
function meta_string(meta, key)
  local val = meta[key]
  if not val then return nil end
  if type(val) == "string" then return val end
  if val.t == "MetaString" then return val[1] or tostring(val) end
  if val.t == "MetaInlines" then return render_inlines(val) end
  return tostring(val)
end

--- Escape a string for Nickel double-quoted strings.
function escape_nickel(s)
  if not s then return "" end
  return s:gsub('\\', '\\\\'):gsub('"', '\\"'):gsub('\n', '\\n')
end

--- Render inline elements to plain text.
function render_inlines(inlines)
  local result = {}
  for _, inline in ipairs(inlines) do
    table.insert(result, render_inline(inline))
  end
  return table.concat(result)
end

--- Render a single inline element to plain text.
function render_inline(inline)
  if inline.t == "Str" then
    return inline.text
  elseif inline.t == "Space" then
    return " "
  elseif inline.t == "SoftBreak" or inline.t == "LineBreak" then
    return "\n"
  elseif inline.t == "Strong" then
    return "**" .. render_inlines(inline.content) .. "**"
  elseif inline.t == "Emph" then
    return "*" .. render_inlines(inline.content) .. "*"
  elseif inline.t == "Code" then
    return "`" .. inline.text .. "`"
  elseif inline.t == "Span" then
    return render_inlines(inline.content)
  elseif inline.t == "Link" then
    return render_inlines(inline.content)
  elseif inline.t == "RawInline" then
    return inline.text
  else
    return ""
  end
end

--- Render a block as inline text (for list items).
function render_block_inline(block)
  if block.t == "Plain" or block.t == "Para" then
    return render_inlines(block.content)
  elseif block.t == "CodeBlock" then
    return block.text
  else
    return ""
  end
end

--- Template (optional — for standalone output).
function Template()
  return "$body$"
end