@rtrentjones/greenlight 0.2.5 → 0.2.6

package/README.md

@@ -0,0 +1,81 @@
+# @rtrentjones/greenlight
+
+The Greenlight CLI — setup and lifecycle for the [Greenlight](https://github.com/RTrentJones/greenlight)
+harness. Greenlight is a **clone-and-own** baseline that turns a domain + API tokens into a live
+personal site plus a self-verifying agentic deploy loop, with plug-and-play subdomain tools (web apps
+or MCP servers). It is provider-agnostic and free-tier-first, and it **edits declarative
+infrastructure-as-code — your CI/CD applies it**. It is not a hosted PaaS.
+
+This is the **single published package**: the CLI, with the framework libraries
+(`shared`/`verify`/`adapters`/`loop`) bundled in. The Terraform modules are distributed as git tags
+(pinned in lockstep with this package's version); the skills ship as a Claude Code plugin.
+
+## Install
+
+```bash
+pnpm add @rtrentjones/greenlight      # or npm i / yarn add
+```
+
+A personal site is a **thin consumer** that depends on this package and owns only its manifest
+(`greenlight.config.ts`) + content. Update with `pnpm update @rtrentjones/greenlight` — no framework
+code to merge.
+
+Optional peer features lazy-load and degrade to a failing check if absent (never a crash):
+
+```bash
+pnpm add -D playwright @anthropic-ai/sdk     # only for verify modes agent-web / eval
+```
+
+## CLI
+
+```bash
+greenlight <command>
+```
+
+| Command | What it does |
+|---|---|
+| `init --domain <d>` | scaffold the manifest + secrets store |
+| `add <name> --lane <l> --target <t> [--data --auth --envs]` | **infra editor**: manifest entry → emit `infra/<name>.tf` + gather/verify tokens + wire the kit (never applies) |
+| `adopt <name> --repo <url\|path> --lane --target` | onboard an existing tool repo (submodule wrapper, or `--standalone`) |
+| `secrets gather <name> [--repo o/r] [--oci-config <path>]` | guided, link-first token prompts straight to GitHub secrets (no disk, no logs) |
+| `secrets sync [--repo o/r] [--env <env>]` | push `.greenlight/secrets.env` → GitHub Actions secrets |
+| `agent sync` | materialize the agent loop kit (skill + `.mcp.json` + CLAUDE block) into a repo |
+| `preview <name>` | build + serve locally + verify in one command |
+| `verify <name> --env <beta\|prod>` (or `--url`) | run the shared verify harness |
+| `promote <name>` | gated `develop → main` fast-forward (after beta verify) |
+| `deploy <name>` | target deploy hook (e.g. OCI restart = re-pull) |
+| `doctor` / `config` | health checks / load + validate + print the manifest |
+
+## The loop
+
+```
+greenlight add notes --lane mcp --target oci   # one entry → Terraform + tokens + kit
+greenlight verify notes --env beta             # api | mcp | playwright | test | agent-web | eval
+greenlight promote notes                        # gated develop → main, after beta verify passes
+```
+
+The `verify` gate is the same code CI **and** the agent run — so changes ship with objective
+confidence, not vibes.
+
+## Programmatic API
+
+Typed helpers for your `greenlight.config.ts` and `verify.config.ts`:
+
+```ts
+import { defineConfig, defineVerify } from '@rtrentjones/greenlight';
+
+export default defineConfig({
+  domain: 'you.dev',
+  tools: { notes: { lane: 'mcp', target: 'oci', data: 'none', auth: 'bearer' } },
+});
+```
+
+Also exported: `loadConfig`, and the `GreenlightConfig` / `VerifySpec` types.
+
+## Links
+
+- **Repo + full docs:** <https://github.com/RTrentJones/greenlight>
+- **Architecture:** [docs/architecture.md](https://github.com/RTrentJones/greenlight/blob/main/docs/architecture.md)
+- **Spec:** [greenlight-v1.md](https://github.com/RTrentJones/greenlight/blob/main/greenlight-v1.md)
+
+MIT

package/assets/skills/provider-cloudflare/SKILL.md

@@ -12,10 +12,12 @@ blog and throwaway MCP dev targets.
 
 ## Token — `CLOUDFLARE_API_TOKEN`
 
-One token, **two scopes** (the trap that took down a live apply):
+One token, these scopes (a missing scope took down a live apply more than once):
 - **Account · Workers Scripts · Edit** — deploy the keepalive worker / workers-target tools.
 - **Zone · DNS · Edit** — the subdomain CNAMEs.
 - **Account · Account Settings · Read** — read account id.
+- **Account · Cloudflare Tunnel · Edit** — only if a tool uses `target: oci` (the cloudflared
+  tunnel). Without it, the tunnel resource fails with **403 Forbidden** on `cfd_tunnel` at apply.
 
 Create at dash → My Profile → API Tokens → Custom Token. Store in `.greenlight/secrets.env`
 (gitignored) and push to GitHub Actions with `greenlight secrets sync`. `greenlight add`

package/assets/skills/provider-github/SKILL.md

@@ -18,6 +18,19 @@ workflows. The `develop → main` flow is standardized (PR → preview, `develop
   use a fine-grained **PAT** with the minimal scopes (e.g. `Secrets: write`, `Administration`
   for protection). Prefer **GitHub OIDC → cloud** over long-lived cloud tokens where supported.
 
+### Poly-repo deploy loop — the two option-B PATs
+
+An adopted tool (submodule) and its wrapper hand off via two fine-grained PATs (`secrets gather`
+pushes each to the right repo; see docs/provider-tokens.md):
+
+- **`GREENLIGHT_DISPATCH_TOKEN`** — on the **tool** repo, scoped **Contents: write** on the
+  **wrapper** → the tool's build fires `repository_dispatch` so the wrapper deploys.
+- **`GREENLIGHT_STATUS_TOKEN`** — on the **wrapper** repo, scoped **Commit statuses: write** on the
+  **tool** → the wrapper posts deploy/verify status back to the tool's commit.
+
+Provider creds (OCI/Cloudflare/…) live **only in the wrapper**; the tool repo holds just the
+dispatch PAT (its build pushes to GHCR with the built-in `github.token`).
+
 ## Secrets sync
 
 `greenlight secrets sync [--repo o/r] [--env <env>]` pushes `.greenlight/secrets.env` to the

package/assets/skills/provider-oci/SKILL.md

@@ -37,9 +37,10 @@ The `oci` provider (auth below) is added to `infra/main.tf`.
 `greenlight secrets gather <tool> --repo <o/r>` pushes the OCI creds straight to GitHub secrets
 (hidden prompts, no disk/logs). **The only manual OCI inputs are the API-key auth values** —
 `TF_VAR_OCI_TENANCY_OCID`, `TF_VAR_OCI_USER_OCID`, `TF_VAR_OCI_FINGERPRINT`, `TF_VAR_OCI_PRIVATE_KEY`
-(PEM), `TF_VAR_OCI_REGION` — plus `OCI_CONTAINER_INSTANCE_OCID` (the Terraform output, set after the
-first apply, for deploy). `TF_VAR_OCI_COMPARTMENT_ID` is **optional** (blank → the tenancy/root
-compartment). Auth is API-key request signing — no bearer, so no fetch-verify.
+(PEM), `TF_VAR_OCI_REGION`. `TF_VAR_OCI_COMPARTMENT_ID` is **optional** (blank → the tenancy/root
+compartment). Auth is API-key request signing — no bearer, so no fetch-verify. The container
+instance OCID is **not** a manual input — the deploy workflow resolves it at deploy time from OCI
+by the instance's display name (= the tool name), so it's abstracted from the developer.
 
 **The VCN, subnet, and availability domain are NOT manual** — they're Terraform: the `oci-network`
 module creates the VCN + a public (egress-only) subnet, and the container-instance module looks the

package/dist/bin.js

@@ -5,7 +5,7 @@ import {
   loadConfig,
   resolveUrl,
   verifyAll
-} from "./chunk-KFKYLGFX.js";
+} from "./chunk-LM6M3DIV.js";
 import "./chunk-XBDQJVAX.js";
 import "./chunk-WFZTRXBF.js";
 import "./chunk-KP3Y6WRU.js";
@@ -92,7 +92,8 @@ function addTool(config, t) {
         envs: t.envs ?? ["beta", "prod"],
         ...t.dir !== void 0 ? { dir: t.dir } : {},
         ...t.adopted ? { adopted: true } : {},
-        ...t.external ? { external: true } : {}
+        ...t.external ? { external: true } : {},
+        ...t.port !== void 0 ? { port: t.port } : {}
       }
     ]
   };
@@ -185,16 +186,17 @@ var PACKS = [
     always: true,
     // the zone/DNS provider + Workers (keepalive) for every Greenlight setup
     appliesTo: () => true,
-    guide: "docs/provider-tokens.md \u2014 CLOUDFLARE_API_TOKEN (Workers Scripts:Edit + Zone DNS:Edit)",
+    guide: "docs/provider-tokens.md \u2014 CLOUDFLARE_API_TOKEN (Workers Scripts:Edit + Zone DNS:Edit + Cloudflare Tunnel:Edit for oci tools)",
     setupUrl: "https://dash.cloudflare.com/profile/api-tokens",
     tokens: [
       {
         envVar: "CLOUDFLARE_API_TOKEN",
-        label: "API token \u2014 Workers Scripts:Edit + Zone DNS:Edit",
+        label: "API token \u2014 Workers Scripts:Edit + Zone DNS:Edit (+ Cloudflare Tunnel:Edit for oci)",
         scopes: [
           "Account \xB7 Workers Scripts \xB7 Edit",
           "Zone \xB7 DNS \xB7 Edit",
-          "Account \xB7 Account Settings \xB7 Read"
+          "Account \xB7 Account Settings \xB7 Read",
+          "Account \xB7 Cloudflare Tunnel \xB7 Edit (only if a tool uses target: oci)"
         ],
         verify: async (t) => {
           const r = await fetch("https://api.cloudflare.com/client/v4/user/tokens/verify", {
@@ -385,7 +387,7 @@ function tokensForTool(tool) {
 }
 
 // src/version.ts
-var MODULE_REF = "v0.2.5";
+var MODULE_REF = "v0.2.6";
 var MODULE_SOURCE_BASE = "git::https://github.com/RTrentJones/greenlight.git//infra/modules";
 function moduleSource(module, ref = MODULE_REF) {
   return `${MODULE_SOURCE_BASE}/${module}?ref=${ref}`;
@@ -395,6 +397,7 @@ function moduleSource(module, ref = MODULE_REF) {
 var hcl = (s) => s.replace(/\n{3,}/g, "\n\n").trimEnd();
 function emitToolTf(opts) {
   const { name, domain, lane, target, data, envs, ref = MODULE_REF } = opts;
+  const port = opts.port ?? 8e3;
   const slug = opts.slug ?? `OWNER/${name}`;
   const useSupabase = data === "supabase";
   const useVercel = target === "vercel";
@@ -467,7 +470,7 @@ variable "${name}_vercel_project_id" {
   }
   if (useOci) {
     blocks.push(`# OCI Container Instance (Always-Free Ampere A1) running the tool's GHCR image + a cloudflared
-# sidecar; the tunnel routes ${name}.${domain} \u2192 the container at localhost:8000. The tool's OWN
+# sidecar; the tunnel routes ${name}.${domain} \u2192 the container at localhost:${port}. The tool's OWN
 # CI builds + pushes the image (provider-agnostic); deploy = restart the instance (re-pull).
 # beta would be a second instance + tunnel route \u2014 mind the free 2-OCPU / 12-GB A1 cap.
 module "${name}_tunnel" {
@@ -476,7 +479,7 @@ module "${name}_tunnel" {
   account_id = var.cloudflare_account_id
   name       = "${name}-tunnel"
   ingress = [
-    { hostname = "${name}.${domain}", service = "http://localhost:8000" },
+    { hostname = "${name}.${domain}", service = "http://localhost:${port}" },
   ]
 }
 
@@ -560,11 +563,13 @@ function emitWrapperMainTf(opts) {
   if (need.has("supabase")) providerBlocks.push('provider "supabase" {}');
   if (need.has("oci")) {
     providerBlocks.push(`provider "oci" {
-  tenancy_ocid = var.oci_tenancy_ocid
-  user_ocid    = var.oci_user_ocid
-  fingerprint  = var.oci_fingerprint
+  # trimspace guards against a trailing newline/space in a pasted secret (a malformed region
+  # makes the identity endpoint hostname fail to resolve \u2014 "no such host" \u2014 at plan time).
+  tenancy_ocid = trimspace(var.oci_tenancy_ocid)
+  user_ocid    = trimspace(var.oci_user_ocid)
+  fingerprint  = trimspace(var.oci_fingerprint)
   private_key  = var.oci_private_key
-  region       = var.oci_region
+  region       = trimspace(var.oci_region)
 }`);
   }
   const vars = ['variable "cloudflare_zone_id" { type = string }'];
@@ -1039,7 +1044,7 @@ async function addCommand(args) {
   const name = args[0];
   if (!name || name.startsWith("-")) {
     throw new Error(
-      "usage: greenlight add <name> --lane <lane> --target <target> [--data <d>] [--auth <a>] [--envs beta,prod]"
+      "usage: greenlight add <name> --lane <lane> --target <target> [--data <d>] [--auth <a>] [--envs beta,prod] [--port 8000]"
     );
   }
   const lane = flag2(args, "--lane");
@@ -1049,13 +1054,15 @@ async function addCommand(args) {
   if (path.endsWith(".example.ts")) {
     throw new Error("no greenlight.config.ts \u2014 run `greenlight init` first");
   }
+  const portFlag = flag2(args, "--port");
   const next = addTool(config, {
     name,
     lane,
     target,
     data: flag2(args, "--data"),
     auth: flag2(args, "--auth"),
-    envs: flag2(args, "--envs")?.split(",")
+    envs: flag2(args, "--envs")?.split(","),
+    port: portFlag ? Number(portFlag) : void 0
   });
   const entry = next.tools.find((t) => t.name === name);
   const data = entry?.data ?? "none";
@@ -1094,7 +1101,10 @@ async function addCommand(args) {
   if (existsSync6(toolTf)) {
     console.log(`\xB7 infra/${name}.tf exists \u2014 left as-is`);
   } else {
-    writeFileSync3(toolTf, emitToolTf({ name, domain: config.domain, lane, target, data, envs }));
+    writeFileSync3(
+      toolTf,
+      emitToolTf({ name, domain: config.domain, lane, target, data, envs, port: entry?.port })
+    );
     console.log(`\u2714 wrote infra/${name}.tf (modules: ${providers.join(", ")})`);
   }
   if (!args.includes("--no-tokens")) {
@@ -1356,7 +1366,7 @@ jobs:
       - uses: jdx/mise-action@v2
       - run: pnpm install --frozen-lockfile
       - run: pip install --quiet oci-cli
-      - name: Deploy (restart container instance -> re-pull GHCR image)
+      - name: Deploy (resolve instance OCID by name -> restart -> re-pull GHCR image)
         env:
           # The OCI CLI reuses the SAME TF_VAR_OCI_* secrets the apply uses \u2014 one secret set.
           OCI_CLI_TENANCY: \${{ secrets.TF_VAR_OCI_TENANCY_OCID }}
@@ -1364,8 +1374,31 @@ jobs:
           OCI_CLI_FINGERPRINT: \${{ secrets.TF_VAR_OCI_FINGERPRINT }}
           OCI_CLI_KEY_CONTENT: \${{ secrets.TF_VAR_OCI_PRIVATE_KEY }}
           OCI_CLI_REGION: \${{ secrets.TF_VAR_OCI_REGION }}
-          OCI_CONTAINER_INSTANCE_OCID: \${{ secrets.OCI_CONTAINER_INSTANCE_OCID }}
-        run: pnpm exec greenlight deploy ${name} --env prod
+          OCI_COMPARTMENT_ID: \${{ secrets.TF_VAR_OCI_COMPARTMENT_ID }}
+        run: |
+          # The instance OCID is abstracted from the developer: resolve it from OCI by the
+          # instance's display name (= the tool name, set by the oci-container-instance module).
+          # No manually-fetched/stored OCID secret. Compartment falls back to the tenancy (root).
+          set -o pipefail
+          COMPARTMENT="\${OCI_COMPARTMENT_ID:-$OCI_CLI_TENANCY}"
+          echo "Resolving '${name}' (region=$OCI_CLI_REGION)\u2026"
+          oci container-instances container-instance list \\
+            --compartment-id "$COMPARTMENT" --display-name ${name} --all > list.json \\
+            || { echo "::error::oci list failed (auth/region/compartment) \u2014 see output above"; exit 1; }
+          # OCIDs are identifiers, not secrets (tenancy/compartment are masked by Actions).
+          echo "Matches:"; jq -r '(.data.items // .data // [])[]? | "  \\(.["lifecycle-state"] // "?")  \\(.id)"' list.json
+          OCID=$(jq -r '[(.data.items // .data // [])[]? | select((.["lifecycle-state"] // "")=="ACTIVE") | .id][0] // ""' list.json)
+          if [ -z "$OCID" ]; then
+            echo "::error::no ACTIVE container instance named '${name}' in compartment $COMPARTMENT"
+            exit 1
+          fi
+          echo "Resolved ${name} instance: $OCID"
+          OCI_CONTAINER_INSTANCE_OCID="$OCID" pnpm exec greenlight deploy ${name} --env prod
+      - name: Verify prod (gate the signal on real health, not just the restart)
+        # The deploy "succeeds" only if the NEW image is actually serving. verify has a built-in
+        # readiness wait (re-pull + container start). A failure here fails the job \u2192 the status
+        # posted back is red. oci is verify-gated direct-to-prod (no cheap standing beta on free A1).
+        run: pnpm exec greenlight verify ${name} --env prod
       - name: Report status back to ${toolRepo}
         if: \${{ always() && github.event.client_payload.sha != '' }}
         env:
@@ -1488,7 +1521,7 @@ Next:
     git commit && git push      # CI (infra.yml) applies. Tool's CI builds; wrapper deploys.${target === "oci" ? `
   Secrets (guided): greenlight secrets gather ${name} --repo <wrapper>   # TF_VAR_OCI_* + GREENLIGHT_STATUS_TOKEN
                     greenlight secrets gather ${name} --repo ${slug}   # GREENLIGHT_DISPATCH_TOKEN
-  After apply, set OCI_CONTAINER_INSTANCE_OCID (the TF output) in the wrapper.` : ""}`);
+  The instance OCID is auto-resolved by the deploy workflow (by display name) \u2014 nothing to set.` : ""}`);
 }
 async function adoptStandalone(ctx) {
   const { name, repoArg, lane, target, data, auth, envs, domain, reg, regPath } = ctx;
@@ -1710,7 +1743,7 @@ async function deployCommand(args) {
   }
   const { config } = await loadManifest();
   const entry = resolveEntry(config, name);
-  if (entry.external) {
+  if (entry.external && entry.target !== "oci") {
     throw new Error(`"${name}" is external (registry pointer) \u2014 deploy it from its own repo`);
   }
   const adapter = createAdapter(entry.target, { domain: config.domain, name: entry.name });

package/dist/{chunk-KFKYLGFX.js → chunk-LM6M3DIV.js}

@@ -33,6 +33,10 @@ var ToolSchema = z.object({
   access: AccessEnum.default("public"),
   envs: z.array(EnvEnum).nonempty("a tool needs at least one env"),
   adopted: z.boolean().default(false),
+  // The port the container listens on (target: oci). The tunnel routes to localhost:<port>;
+  // defaults to 8000 (the mcp/FastMCP convention). Set it for a lane:docker tool on a different
+  // port so the oci modules stay generic. Ignored by non-oci targets.
+  port: z.number().int().positive().optional(),
   // Directory the tool builds/deploys from. Defaults to tools/<name>; a standalone
   // (poly-repo) tool sets '.' (the repo root).
   dir: z.string().optional(),

package/dist/index.js

@@ -2,7 +2,7 @@ import {
   defineConfig,
   defineVerify,
   loadConfig
-} from "./chunk-KFKYLGFX.js";
+} from "./chunk-LM6M3DIV.js";
 import "./chunk-XBDQJVAX.js";
 import "./chunk-WFZTRXBF.js";
 import "./chunk-KP3Y6WRU.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rtrentjones/greenlight",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Greenlight CLI — setup and lifecycle for the harness.",
   "license": "MIT",
   "repository": {
@@ -32,9 +32,9 @@
   },
   "devDependencies": {
     "@rtrentjones/greenlight-adapters": "0.2.4",
+    "@rtrentjones/greenlight-loop": "0.2.4",
     "@rtrentjones/greenlight-shared": "0.2.4",
-    "@rtrentjones/greenlight-verify": "0.2.4",
-    "@rtrentjones/greenlight-loop": "0.2.4"
+    "@rtrentjones/greenlight-verify": "0.2.4"
   },
   "scripts": {
     "build": "node scripts/copy-assets.mjs && tsup",