@intentius/plywood 0.0.0-stage → 0.1.0

package/presets/dashboards/plywood.json

@@ -0,0 +1,83 @@
+{
+  "title": "plywood",
+  "description": "plywood's runs from chant's OTLP traces (chant#4555), read through a Tempo data source. Span attributes carry the plywood. prefix.",
+  "uid": "plywood-runs",
+  "schemaVersion": 39,
+  "version": 1,
+  "editable": true,
+  "time": { "from": "now-7d", "to": "now" },
+  "tags": ["plywood", "pulumi", "chant"],
+  "templating": {
+    "list": [
+      { "name": "tempo", "label": "Traces", "type": "datasource", "query": "tempo" },
+      {
+        "name": "stack",
+        "label": "Stack",
+        "type": "custom",
+        "query": ".*",
+        "current": { "text": "all", "value": ".*" },
+        "description": "A regular expression over plywood.stack, such as shop/prod-.*"
+      }
+    ]
+  },
+  "panels": [
+    {
+      "id": 1,
+      "type": "table",
+      "title": "Runs",
+      "gridPos": { "x": 0, "y": 0, "w": 24, "h": 8 },
+      "datasource": { "type": "tempo", "uid": "${tempo}" },
+      "targets": [{ "refId": "A", "queryType": "traceql", "query": "{ resource.service.name = \"plywood\" && span.plywood.run.id != nil }", "limit": 50 }]
+    },
+    {
+      "id": 2,
+      "type": "table",
+      "title": "Updates per stack",
+      "gridPos": { "x": 0, "y": 8, "w": 12, "h": 8 },
+      "datasource": { "type": "tempo", "uid": "${tempo}" },
+      "targets": [{ "refId": "A", "queryType": "traceql", "query": "{ span.plywood.stack =~ \"${stack}\" && span.plywood.up.result != nil } | select(span.plywood.stack, span.plywood.engine, span.plywood.up.result, span.plywood.up.duration_s)", "limit": 100 }]
+    },
+    {
+      "id": 3,
+      "type": "table",
+      "title": "Failed updates",
+      "gridPos": { "x": 12, "y": 8, "w": 12, "h": 8 },
+      "datasource": { "type": "tempo", "uid": "${tempo}" },
+      "targets": [{ "refId": "A", "queryType": "traceql", "query": "{ span.plywood.stack =~ \"${stack}\" && (span.plywood.up.result = \"failed\" || span.plywood.failure.code != nil) } | select(span.plywood.stack, span.plywood.failure.code, span.plywood.failure.exit_code)", "limit": 100 }]
+    },
+    {
+      "id": 4,
+      "type": "timeseries",
+      "title": "Update duration (s)",
+      "gridPos": { "x": 0, "y": 16, "w": 12, "h": 8 },
+      "datasource": { "type": "tempo", "uid": "${tempo}" },
+      "targets": [{ "refId": "A", "queryType": "traceqlmetrics", "query": "{ span.plywood.stack =~ \"${stack}\" && span.plywood.up.duration_s != nil } | quantile_over_time(span.plywood.up.duration_s, .5, .95) by (span.plywood.stack)" }]
+    },
+    {
+      "id": 5,
+      "type": "table",
+      "title": "Waits for an approval",
+      "gridPos": { "x": 12, "y": 16, "w": 12, "h": 8 },
+      "datasource": { "type": "tempo", "uid": "${tempo}" },
+      "targets": [{ "refId": "A", "queryType": "traceql", "query": "{ event:name = \"gate-waiting\" } | select(event.plywood.gate.op, event.gate)", "limit": 50 }]
+    },
+    {
+      "id": 6,
+      "type": "table",
+      "title": "plunge updates per stack",
+      "description": "Stacks on plunge: the resources an update wrote, its provider and record time, and its slowest call.",
+      "gridPos": { "x": 0, "y": 24, "w": 12, "h": 8 },
+      "datasource": { "type": "tempo", "uid": "${tempo}" },
+      "targets": [{ "refId": "A", "queryType": "traceql", "query": "{ span.plywood.stack =~ \"${stack}\" && span.plywood.plunge.resources != nil } | select(span.plywood.stack, span.plywood.plunge.resources, span.plywood.plunge.calls, span.plywood.plunge.provider_ms, span.plywood.plunge.record_ms, span.plywood.plunge.failed_calls, span.plywood.plunge.slowest.urn, span.plywood.plunge.slowest.ms)", "limit": 100 }]
+    },
+    {
+      "id": 7,
+      "type": "table",
+      "title": "plunge updates per resource",
+      "description": "One row per resource a plunge update wrote, with its provider and record time.",
+      "gridPos": { "x": 12, "y": 24, "w": 12, "h": 8 },
+      "datasource": { "type": "tempo", "uid": "${tempo}" },
+      "targets": [{ "refId": "A", "queryType": "traceql", "query": "{ span.plywood.plunge.calls != nil && span.plywood.plunge.resources = nil } | select(span.plywood.resource.type, span.plywood.resource.name, span.plywood.plunge.calls, span.plywood.plunge.provider_ms, span.plywood.plunge.record_ms)", "limit": 200 }]
+    }
+  ]
+}

package/presets/policy/plywood-providers/PulumiPolicy.yaml

@@ -0,0 +1,2 @@
+description: plywood's provider allowlist, from plywood.yml's policy.providers
+runtime: nodejs

package/presets/policy/plywood-providers/index.ts

@@ -0,0 +1,29 @@
+// plywood's provider allowlist as a CrossGuard pack. 'plywood init' writes it
+// with plywood-providers.json beside it, the list from plywood.yml's
+// policy.providers; list the pack under policy.packs with that config to run
+// it in every preview and update. A resource whose provider package is not
+// listed is a mandatory violation, which denies at chant's gate.
+import { PolicyPack } from "@pulumi/policy";
+
+/** The provider package of a Pulumi type, or undefined for the engine's own types. */
+function packageOf(type: string): string | undefined {
+  if (type.startsWith("pulumi:providers:")) return type.slice("pulumi:providers:".length);
+  if (type.startsWith("pulumi:") || type === "unknown") return undefined;
+  return type.split(":")[0];
+}
+
+new PolicyPack("plywood-providers", {
+  policies: [
+    {
+      name: "provider-allowlist",
+      description: "Every resource comes from a provider package plywood.yml's policy.providers lists.",
+      enforcementLevel: "mandatory",
+      configSchema: { properties: { allowed: { type: "array", items: { type: "string" } } } },
+      validateResource: (args, reportViolation) => {
+        const allowed = args.getConfig<{ allowed?: string[] }>().allowed ?? [];
+        const pkg = packageOf(args.type);
+        if (pkg !== undefined && !allowed.includes(pkg)) reportViolation(`${args.urn} uses the provider package ${pkg}, which policy.providers does not list`);
+      },
+    },
+  ],
+});

package/presets/policy/plywood-providers/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "plywood-providers",
+  "version": "0.1.0",
+  "private": true,
+  "main": "index.ts",
+  "dependencies": {
+    "@pulumi/policy": "^1.13.0",
+    "@pulumi/pulumi": "^3.0.0"
+  }
+}

package/presets/policy/plywood_providers.rego.tmpl

@@ -0,0 +1,31 @@
+# Written by 'plywood init' from plywood.yml's policy.providers: edit the
+# list there and run 'plywood init' again. chant's gate reads the change set
+# as input.changeSet; a resource the change creates, updates or replaces
+# whose provider package is not listed denies the preview.
+package {{namespace}}
+
+import rego.v1
+
+allowed := {{allowed}}
+
+# The provider package of a Pulumi type: aws for aws:s3/bucket:Bucket, and
+# for a provider resource (pulumi:providers:aws) the package it provides.
+package_of(t) := p if {
+	startswith(t, "pulumi:providers:")
+	p := substring(t, count("pulumi:providers:"), -1)
+}
+
+package_of(t) := p if {
+	not startswith(t, "pulumi:")
+	t != "unknown"
+	p := split(t, ":")[0]
+}
+
+deny_provider_package contains msg if {
+	some e in input.changeSet.entries
+	e.lexicon == "pulumi"
+	e.action in {"create", "update", "replace"}
+	p := package_of(e.type)
+	not p in allowed
+	msg := sprintf("%s uses the provider package %s, which policy.providers does not list", [e.address, p])
+}

package/templates/agent-guard/bin/plunge

@@ -0,0 +1,27 @@
+#!/bin/sh
+# plywood's agent guard wrapper for plunge (plywood#19), written by 'plywood guard install'.
+# First on PATH in an agent session: with PLYWOOD_AGENT_GUARD=1 or CLAUDECODE=1
+# it refuses 'plunge up', 'plunge update' and 'plunge destroy', and runs every other
+# command with the real plunge further down PATH.
+self_dir=$(cd "$(dirname "$0")" && pwd)
+if [ "${PLYWOOD_AGENT_GUARD:-}" = "1" ] || [ "${CLAUDECODE:-}" = "1" ]; then
+  skip=0
+  for arg in "$@"; do
+    if [ "$skip" = 1 ]; then skip=0; continue; fi
+    case "$arg" in
+      -C|--cwd|-s|--stack|--color|--config-file|--logflow|-v|--verbose|--tracing|--profiling|--memprofilerate) skip=1 ;;
+      -*) ;;
+      up|update|destroy)
+        echo "plywood guard: an agent session does not run 'plunge $arg'. Open a pull request; plywood previews it, and the update runs after a person approves the digest." >&2
+        exit 1 ;;
+      *) break ;;
+    esac
+  done
+fi
+IFS=:
+for dir in $PATH; do
+  [ "$(cd "$dir" 2>/dev/null && pwd)" = "$self_dir" ] && continue
+  if [ -x "$dir/plunge" ]; then exec "$dir/plunge" "$@"; fi
+done
+echo "plywood guard: no plunge on PATH after $self_dir" >&2
+exit 127

package/templates/agent-guard/bin/pulumi

@@ -0,0 +1,27 @@
+#!/bin/sh
+# plywood's agent guard wrapper for pulumi (plywood#19), written by 'plywood guard install'.
+# First on PATH in an agent session: with PLYWOOD_AGENT_GUARD=1 or CLAUDECODE=1
+# it refuses 'pulumi up', 'pulumi update' and 'pulumi destroy', and runs every other
+# command with the real pulumi further down PATH.
+self_dir=$(cd "$(dirname "$0")" && pwd)
+if [ "${PLYWOOD_AGENT_GUARD:-}" = "1" ] || [ "${CLAUDECODE:-}" = "1" ]; then
+  skip=0
+  for arg in "$@"; do
+    if [ "$skip" = 1 ]; then skip=0; continue; fi
+    case "$arg" in
+      -C|--cwd|-s|--stack|--color|--config-file|--logflow|-v|--verbose|--tracing|--profiling|--memprofilerate) skip=1 ;;
+      -*) ;;
+      up|update|destroy)
+        echo "plywood guard: an agent session does not run 'pulumi $arg'. Open a pull request; plywood previews it, and the update runs after a person approves the digest." >&2
+        exit 1 ;;
+      *) break ;;
+    esac
+  done
+fi
+IFS=:
+for dir in $PATH; do
+  [ "$(cd "$dir" 2>/dev/null && pwd)" = "$self_dir" ] && continue
+  if [ -x "$dir/pulumi" ]; then exec "$dir/pulumi" "$@"; fi
+done
+echo "plywood guard: no pulumi on PATH after $self_dir" >&2
+exit 127

package/templates/agent-guard/plywood-guard.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+// plywood's agent guard, a Claude Code PreToolUse hook on Bash (plywood#19).
+// Written by `plywood guard install`; `plywood guard install` writes it again.
+// It blocks a command line that runs `pulumi up`, `pulumi destroy` or
+// `plunge up` (and `update`, their alias): an agent opens a pull request,
+// and the update runs after a person approves its digest. Exit 2 is Claude
+// Code's code for a blocked call; its stderr goes back to the agent.
+
+const GUARDED = { pulumi: ["up", "update", "destroy"], plunge: ["up", "update", "destroy"] };
+const VALUED_GLOBALS = new Set(["-C", "--cwd", "-s", "--stack", "--color", "--config-file", "--logflow", "-v", "--verbose", "--tracing", "--profiling", "--memprofilerate"]);
+const LAUNCHERS = new Set(["env", "npx", "sudo", "command", "exec", "nohup", "time", "xargs"]);
+
+function segments(line) {
+  return line
+    .split(/\|\||&&|[;|\n`]|\$\(|\)/)
+    .map((seg) => (seg.match(/'[^']*'|"[^"]*"|\S+/g) ?? []).map((t) => t.replace(/^['"]|['"]$/g, "")))
+    .filter((t) => t.length > 0);
+}
+
+/** The refused engine and subcommand, or undefined. Kept in step with src/guard.ts `guardVerdict`. */
+export function verdict(line) {
+  for (const words of segments(line)) {
+    let i = 0;
+    while (i < words.length && (LAUNCHERS.has(words[i]) || /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i]) || (words[i - 1] === "env" && words[i].startsWith("-")))) i++;
+    const bin = (words[i] ?? "").split("/").pop();
+    const refused = GUARDED[bin];
+    if (!refused) continue;
+    for (let j = i + 1; j < words.length; j++) {
+      const w = words[j];
+      if (w.startsWith("-")) {
+        if (VALUED_GLOBALS.has(w)) j++;
+        continue;
+      }
+      if (refused.includes(w)) return { engine: bin, subcommand: w };
+      break;
+    }
+  }
+  return undefined;
+}
+
+async function main() {
+  let input = "";
+  for await (const chunk of process.stdin) input += chunk;
+  let call;
+  try {
+    call = JSON.parse(input);
+  } catch {
+    return 0;
+  }
+  const command = call?.tool_input?.command;
+  if (typeof command !== "string") return 0;
+  const v = verdict(command);
+  if (!v) return 0;
+  process.stderr.write(`plywood guard: an agent session does not run '${v.engine} ${v.subcommand}'. Open a pull request; plywood previews it, and the update runs after a person approves the digest.\n`);
+  return 2;
+}
+
+if (process.argv[1] && import.meta.url.endsWith("/plywood-guard.mjs") && process.argv[1].endsWith("plywood-guard.mjs")) {
+  main().then((code) => process.exit(code));
+}

package/templates/agent-prompt.md

@@ -0,0 +1,6 @@
+Set up plywood in this repository.
+Read https://intentius.io/plywood/llms.txt first, then
+https://intentius.io/plywood/getting-started/agents/ and follow it.
+Ask me which stacks should wait for an approval before they update.
+Open a pull request with the result.
+Never run `pulumi up`, `plunge up`, `pulumi destroy` or `plywood approve`, override a policy denial, use `--mode up`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.

package/templates/chant.config.ts.tmpl

@@ -0,0 +1,10 @@
+import type { ChantConfig } from "@intentius/chant/config";
+
+/**
+ * Written by plywood init. plywood runs chant's pull request pipeline, and
+ * the pulumi lexicon previews and updates each stack listed in
+ * plywood.component.ts.
+ */
+export default {
+  lexicons: ["pulumi"],
+} satisfies ChantConfig;

package/templates/plywood.yml

@@ -0,0 +1,8 @@
+# yaml-language-server: $schema=https://intentius.io/plywood/plywood.schema.json
+#
+# plywood.yml, written by plywood init. init reads each Pulumi.yaml and its
+# Pulumi.<stack>.yaml files, the backend and the forge from the repository,
+# so this file holds only what it could not settle there. Add a key to
+# change a default; every key is at https://intentius.io/plywood/reference/config/
+# Run plywood init again after adding a stack; it keeps this file as it is.
+{{keys}}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.