@rtrentjones/greenlight 0.2.4 → 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

@@ -1,6 +1,6 @@
 ---
 name: provider-oci
-description: How Oracle Cloud (OCI) works in a Greenlight setup — the `target: oci` runtime for stateful MCP servers (BAMCP) on a free-tier Ampere A1 Container Instance, the provider-agnostic build-via-GitHub→GHCR model, Greenlight-owned compute + tunnel Terraform, the OCI token CLI, deploy = restart, and the Always-Free idle-reclaim trap (PAYG, manual). Use when wiring/debugging an oci-target tool.
+description: How Oracle Cloud (OCI) works in a Greenlight setup — the `target: oci` runtime for stateful MCP servers (BAMCP) on a free-tier Ampere A1 Container Instance, the provider-agnostic build-via-GitHub→GHCR model, Greenlight-owned compute + tunnel Terraform, the OCI token CLI, deploy = restart, and staying on the free tier (no PAYG; recover-on-alert). Use when wiring/debugging an oci-target tool.
 ---
 
 # provider-oci
@@ -34,11 +34,26 @@ The `oci` provider (auth below) is added to `infra/main.tf`.
 
 ## OCI token CLI
 
-`greenlight add`/`init` gather the OCI creds into `.greenlight/secrets.env` (+ GH secrets):
-**provider auth** `TF_VAR_oci_tenancy_ocid`, `TF_VAR_oci_user_ocid`, `TF_VAR_oci_fingerprint`,
-`TF_VAR_oci_private_key` (PEM), `TF_VAR_oci_region`; **placement** `TF_VAR_oci_compartment_id`,
-`TF_VAR_oci_availability_domain`, `TF_VAR_oci_subnet_id`; and `OCI_CONTAINER_INSTANCE_OCID`
-(the Terraform output, for deploy). Auth is API-key request signing — no bearer, so no fetch-verify.
+`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`. `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
+AD up via an `oci_identity_availability_domains` data source. So the bootstrap is just "create one
+API key" — Terraform can't create the credential it needs to authenticate, but it owns everything
+after that. (Out-of-A1-capacity in one AD? set `availability_domain` on the instance module to pin
+another — the only time you touch it.)
+
+**Shortcut — feed the API-key config preview directly.** After *Add API key*, OCI shows a
+"Configuration file preview" (the `[DEFAULT]` block) and you download the `.pem`. Pass both:
+`greenlight secrets gather <tool> --repo <o/r> --oci-config ~/path/config [--oci-key ~/path/key.pem]`
+— it auto-fills the 5 auth secrets (incl. the multi-line PEM, read from the file so it's never
+pasted) and only prompts for the 3 placement values + the option-B deploy PATs.
 
 ## Deploy = restart (re-pull)
 
@@ -46,11 +61,12 @@ The `oci` provider (auth below) is added to `infra/main.tf`.
 --container-instance-id <OCID>` — the instance re-pulls the latest GHCR image. The tool's CI
 builds; an event trigger (the chosen deploy option) fires the restart. The adapter does NOT build.
 
-## The idle-reclaim trap — fixed manually, NOT by code
+## Idle-reclaim — stay free, recover on alert
 
-OCI **Always-Free reclaims idle compute**; pings don't count, only account standing. Convert the
-tenancy to **Pay-As-You-Go** (+ a low billing budget alarm) — a one-time manual change (see
-`docs/oci-payg-runbook.md`). Keepalive only **health-checks** + nags; it cannot stop reclaim.
+OCI Always-Free can reclaim idle compute. We **stay on the free tier** and accept that: the
+instance runs restart-policy ALWAYS, keepalive health-checks it, and if it's ever stopped/reclaimed
+the alert fires and a **re-apply / redeploy** restores it. **PAYG is NOT used** — it's an optional
+last resort (see `docs/oci-payg-runbook.md`) only if reclaim ever becomes a recurring problem.
 
 ## Verify
 The tool is typically an **MCP server**: verify with `mode: mcp`, connect at `<name>.<domain>/mcp`

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 } : {}
       }
     ]
   };
@@ -132,6 +133,7 @@ function resolveEntry(config, name) {
       name: void 0,
       lane: config.blog.lane,
       target: config.blog.target,
+      data: config.blog.data,
       dir: "apps/blog",
       external: false
     };
@@ -145,6 +147,7 @@ function resolveEntry(config, name) {
     name: tool.name,
     lane: tool.lane,
     target: tool.target,
+    data: tool.data,
     dir: tool.dir ?? `tools/${tool.name}`,
     external: tool.external
   };
@@ -183,15 +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", {
@@ -214,6 +219,7 @@ var PACKS = [
     name: "Vercel",
     appliesTo: (t) => t.target === "vercel",
     guide: "docs/provider-tokens.md \u2014 VERCEL_API_TOKEN (team-scoped)",
+    setupUrl: "https://vercel.com/account/settings/tokens",
     tokens: [
       {
         envVar: "VERCEL_API_TOKEN",
@@ -235,6 +241,7 @@ var PACKS = [
     name: "Supabase",
     appliesTo: (t) => t.data === "supabase",
     guide: "docs/provider-tokens.md \u2014 SUPABASE_ACCESS_TOKEN (Management API)",
+    setupUrl: "https://supabase.com/dashboard/account/tokens",
     tokens: [
       {
         envVar: "SUPABASE_ACCESS_TOKEN",
@@ -269,6 +276,7 @@ var PACKS = [
     // remote state backs every wrapper's infra
     appliesTo: () => true,
     guide: "docs/terraform-state-r2.md \u2014 HCP Terraform free tier (no credit card)",
+    setupUrl: "https://app.terraform.io/app/settings/tokens",
     tokens: [
       {
         envVar: "TF_API_TOKEN",
@@ -290,6 +298,7 @@ var PACKS = [
     // secrets sync + repo/branch infra
     appliesTo: () => true,
     guide: "docs/provider-tokens.md \u2014 GitHub (gh auth, or a fine-grained PAT)",
+    setupUrl: "https://github.com/settings/personal-access-tokens/new",
     tokens: [
       {
         envVar: "GITHUB_TOKEN",
@@ -305,7 +314,8 @@ var PACKS = [
     id: "oci",
     name: "Oracle Cloud (OCI)",
     appliesTo: (t) => t.target === "oci",
-    guide: "docs/oci-payg-runbook.md \u2014 Always-Free A1 Container Instance + tunnel (PAYG to stop reclaim)",
+    guide: "docs/oci-payg-runbook.md \u2014 Always-Free A1 Container Instance + tunnel (no PAYG)",
+    setupUrl: "https://cloud.oracle.com \u2014 Profile \u2192 User settings \u2192 Tokens and keys \u2192 Add API key",
     tokens: [
       // OCI provider auth = API-key request signing (no bearer → no cheap fetch verify). These
       // flow to the `oci` Terraform provider as TF_VAR_oci_* (the wrapper apply uses them).
@@ -318,16 +328,12 @@ var PACKS = [
         optional: true
       },
       { envVar: "TF_VAR_oci_region", label: "OCI region, e.g. us-ashburn-1", optional: true },
-      // Container Instance placement (your Always-Free compartment / AD / a public subnet).
-      { envVar: "TF_VAR_oci_compartment_id", label: "OCI compartment OCID", optional: true },
+      // Compartment is the ONLY placement input, and it's optional — blank → the tenancy (root)
+      // compartment. The VCN/subnet are created by the oci-network module and the availability
+      // domain is looked up by a data source, so neither is a manual secret anymore.
       {
-        envVar: "TF_VAR_oci_availability_domain",
-        label: "OCI availability domain",
-        optional: true
-      },
-      {
-        envVar: "TF_VAR_oci_subnet_id",
-        label: "OCI subnet OCID (public, for egress)",
+        envVar: "TF_VAR_oci_compartment_id",
+        label: "OCI compartment OCID (optional \u2014 blank uses the tenancy/root compartment)",
         optional: true
       },
       // Deploy (restart the instance → re-pull). Set from the Terraform output.
@@ -335,11 +341,25 @@ var PACKS = [
         envVar: "OCI_CONTAINER_INSTANCE_OCID",
         label: "container instance OCID (TF output) \u2014 `greenlight deploy` restarts it",
         optional: true
+      },
+      // Option-B event-driven deploy (GitHub PATs). dispatch → set on the TOOL repo;
+      // status → set on the WRAPPER repo. Skip the one that doesn't match `--repo`.
+      {
+        envVar: "GREENLIGHT_DISPATCH_TOKEN",
+        label: "GitHub PAT, Contents:write on the WRAPPER (TOOL repo fires the deploy dispatch)",
+        optional: true,
+        setupUrl: "https://github.com/settings/personal-access-tokens/new"
+      },
+      {
+        envVar: "GREENLIGHT_STATUS_TOKEN",
+        label: "GitHub PAT, Commits:write on the TOOL (WRAPPER posts deploy status back)",
+        optional: true,
+        setupUrl: "https://github.com/settings/personal-access-tokens/new"
       }
     ],
     skill: "provider-oci",
-    tfModules: ["tool", "tunnel", "oci-container-instance"]
-    // DNS + tunnel + compute; deploy = restart
+    // DNS + tunnel + network (VCN/subnet) + compute; deploy = restart.
+    tfModules: ["tool", "tunnel", "oci-network", "oci-container-instance"]
   }
 ];
 function packsForTool(tool) {
@@ -367,7 +387,7 @@ function tokensForTool(tool) {
 }
 
 // src/version.ts
-var MODULE_REF = "v0.2.4";
+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}`;
@@ -377,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";
@@ -384,13 +405,7 @@ function emitToolTf(opts) {
   const envList = envs.map((e) => `"${e}"`).join(", ");
   const blocks = [];
   const assumes = ["var.cloudflare_zone_id"];
-  if (useOci)
-    assumes.push(
-      "var.cloudflare_account_id",
-      "var.oci_compartment_id",
-      "var.oci_availability_domain",
-      "var.oci_subnet_id"
-    );
+  if (useOci) assumes.push("var.cloudflare_account_id", "local.oci_compartment_id");
   if (useSupabase) assumes.push("var.supabase_organization_id", "var.supabase_database_password");
   const ghcrOwner = (slug.split("/")[0] ?? "owner").toLowerCase();
   blocks.push(
@@ -455,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" {
@@ -464,19 +479,27 @@ 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}" },
   ]
 }
 
+# Network is IaC too \u2014 VCN + public subnet (egress only). No hand-clicking in the OCI console.
+module "${name}_network" {
+  source = "${moduleSource("oci-network", ref)}"
+
+  name           = "${name}"
+  compartment_id = local.oci_compartment_id
+}
+
 module "${name}_instance" {
   source = "${moduleSource("oci-container-instance", ref)}"
 
-  name                = "${name}"
-  compartment_id      = var.oci_compartment_id
-  availability_domain = var.oci_availability_domain
-  subnet_id           = var.oci_subnet_id
-  image_url           = var.${name}_image
-  tunnel_token        = module.${name}_tunnel.token
+  name           = "${name}"
+  compartment_id = local.oci_compartment_id
+  subnet_id      = module.${name}_network.subnet_id
+  image_url      = var.${name}_image
+  tunnel_token   = module.${name}_tunnel.token
+  # availability_domain is auto-picked (first AD in the compartment); set it to pin a specific AD.
 
   # Tool runtime env \u2014 fill in (e.g. PORT/listen settings, auth). The container must listen on 8000.
   environment = {}
@@ -540,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 }'];
@@ -561,10 +586,16 @@ function emitWrapperMainTf(opts) {
     vars.push('variable "oci_fingerprint" { type = string }');
     vars.push('variable "oci_private_key" {\n  type      = string\n  sensitive = true\n}');
     vars.push('variable "oci_region" { type = string }');
-    vars.push('variable "oci_compartment_id" { type = string }');
-    vars.push('variable "oci_availability_domain" { type = string }');
-    vars.push('variable "oci_subnet_id" { type = string }');
+    vars.push(
+      'variable "oci_compartment_id" {\n  type    = string\n  default = "" # blank \u2192 tenancy (root) compartment\n}'
+    );
   }
+  const localsBlock = need.has("oci") ? `
+locals {
+  # Compartment for all OCI tools \u2014 blank var.oci_compartment_id falls back to the tenancy (root).
+  oci_compartment_id = var.oci_compartment_id != "" ? var.oci_compartment_id : var.oci_tenancy_ocid
+}
+` : "";
   return `# Wrapper infra (singleton): providers + remote-state backend + shared variables.
 # \`greenlight add\` appends per-tool module blocks as infra/<name>.tf. Apply is CI/CD's job
 # (infra.yml). Fill in the HCP backend below before the first apply (docs/terraform-state-r2.md).
@@ -585,7 +616,7 @@ ${req.join("\n")}
 ${providerBlocks.join("\n")}
 
 ${vars.join("\n")}
-`;
+${localsBlock}`;
 }
 function providersForTool(tool) {
   const ids = new Set(packsForTool(tool).map((p) => p.id));
@@ -599,12 +630,13 @@ function providersForTool(tool) {
 // src/tokens.ts
 import { existsSync as existsSync4, mkdirSync, readFileSync as readFileSync2, writeFileSync } from "fs";
 import { resolve as resolve4 } from "path";
-import { createInterface } from "readline/promises";
+import { createInterface as createInterface2 } from "readline/promises";
 
 // src/commands/secrets.ts
 import { execFileSync } from "child_process";
 import { existsSync as existsSync3, readFileSync } from "fs";
 import { resolve as resolve3 } from "path";
+import { createInterface } from "readline";
 function parseSecretsEnv(text) {
   const out = [];
   for (const raw of text.split("\n")) {
@@ -616,6 +648,36 @@ function parseSecretsEnv(text) {
   }
   return out;
 }
+function parseOciConfig(text) {
+  const out = {};
+  for (const raw of text.split("\n")) {
+    const line = raw.trim();
+    if (line === "" || line.startsWith("#") || line.startsWith("[")) continue;
+    const eq = line.indexOf("=");
+    if (eq <= 0) continue;
+    const key = line.slice(0, eq).trim().toLowerCase();
+    if (!(key in out)) out[key] = line.slice(eq + 1).trim();
+  }
+  return out;
+}
+function ociPrefill(configPath, keyPath) {
+  const cfg = parseOciConfig(readFileSync(configPath, "utf8"));
+  const map = /* @__PURE__ */ new Map();
+  const set = (k, v) => {
+    if (v) map.set(k, v);
+  };
+  set("TF_VAR_OCI_USER_OCID", cfg.user);
+  set("TF_VAR_OCI_FINGERPRINT", cfg.fingerprint);
+  set("TF_VAR_OCI_TENANCY_OCID", cfg.tenancy);
+  set("TF_VAR_OCI_REGION", cfg.region);
+  const pem = keyPath ?? cfg.key_file;
+  if (pem && existsSync3(pem)) {
+    map.set("TF_VAR_OCI_PRIVATE_KEY", readFileSync(pem, "utf8"));
+  } else if (pem) {
+    console.log(`   ! PEM not found at ${pem} \u2014 set TF_VAR_OCI_PRIVATE_KEY manually (--oci-key)`);
+  }
+  return map;
+}
 function parseRepo(remoteUrl) {
   const m = remoteUrl.trim().match(/github\.com[/:]([^/]+)\/(.+?)(?:\.git)?$/);
   return m ? `${m[1]}/${m[2]}` : null;
@@ -669,12 +731,135 @@ function syncSecrets(opts) {
   }
   return { repo, count: entries.length };
 }
+function hiddenPrompter() {
+  const tty = Boolean(process.stdin.isTTY);
+  const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: tty });
+  if (tty) rl._writeToOutput = () => {
+  };
+  return {
+    ask: (query) => new Promise((resolve11) => {
+      process.stdout.write(query);
+      rl.question("", (val) => {
+        process.stdout.write("\n");
+        resolve11(val.trim());
+      });
+    }),
+    close: () => rl.close()
+  };
+}
+function listGitHubSecrets(repo, env) {
+  const ghArgs = ["secret", "list", "--repo", repo, "--json", "name"];
+  if (env) ghArgs.push("--env", env);
+  try {
+    const out = execFileSync("gh", ghArgs, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+      // don't leak gh's stderr into the guided flow
+    });
+    const parsed = JSON.parse(out);
+    return new Set(parsed.map((s) => s.name));
+  } catch {
+    return null;
+  }
+}
+function setGitHubSecret(repo, env, key, value) {
+  const ghArgs = ["secret", "set", key, "--repo", repo];
+  if (env) ghArgs.push("--env", env);
+  try {
+    execFileSync("gh", ghArgs, { input: value });
+  } catch (e) {
+    const err = e;
+    if (err.code === "ENOENT") {
+      throw new Error("the GitHub CLI `gh` is required \u2014 install it and run `gh auth login`");
+    }
+    const detail = err.stderr?.toString().trim();
+    throw new Error(`failed to set ${key}${detail ? `: ${detail}` : " (check `gh auth status`)"}`);
+  }
+}
+async function gatherSecrets(name, repo, env, prefill) {
+  const { config } = await loadManifest();
+  const entry = resolveEntry(config, name);
+  const packs = packsForTool({ target: entry.target, data: entry.data });
+  const dest = env ? `env "${env}" of ${repo}` : repo;
+  const existing = listGitHubSecrets(repo, env);
+  console.log(`Gathering secrets for "${name}" \u2192 GitHub ${dest}`);
+  console.log(
+    "Paste each value (hidden); Enter to skip. Values go straight to GitHub \u2014 never to disk."
+  );
+  console.log(
+    `[already set] = a value exists (paste to override, Enter to keep) \xB7 [not set] = new.${existing ? "" : " (could not read existing secrets \u2014 annotations omitted)"}`
+  );
+  if (prefill?.size) console.log(`Auto-filling ${prefill.size} value(s) from the OCI config.`);
+  console.log("");
+  const prompt = hiddenPrompter();
+  let pushed = 0;
+  try {
+    for (const pack of packs) {
+      console.log(`\u2500\u2500 ${pack.name}${pack.setupUrl ? `  \u2192  ${pack.setupUrl}` : ""}`);
+      for (const tok of pack.tokens) {
+        const key = tok.envVar.toUpperCase();
+        if (key === "GITHUB_TOKEN") {
+          console.log("   \xB7 GITHUB_TOKEN \u2014 provided automatically by Actions; skipping");
+          continue;
+        }
+        const pre = prefill?.get(key);
+        if (pre) {
+          setGitHubSecret(repo, env, key, pre);
+          console.log(`   \u2714 ${existing?.has(key) ? "overrode" : "pushed"} ${key} \u2190 OCI config`);
+          pushed++;
+          continue;
+        }
+        if (tok.scopes?.length) console.log(`   scopes: ${tok.scopes.join(", ")}`);
+        if (tok.setupUrl) console.log(`   link: ${tok.setupUrl}`);
+        const state = existing ? existing.has(key) ? "  [already set]" : "  [not set]" : "";
+        const value = await prompt.ask(`   ${key} \u2014 ${tok.label}${state}
+   value: `);
+        if (!value) {
+          console.log(existing?.has(key) ? "   \xB7 kept existing" : "   \xB7 skipped");
+          continue;
+        }
+        if (tok.verify) {
+          const check = await tok.verify(value, {}).catch((e) => ({ ok: false, detail: e instanceof Error ? e.message : String(e) }));
+          if (!check.ok) {
+            console.log(
+              `   \u2716 verify failed${check.detail ? ` (${check.detail})` : ""} \u2014 not pushed`
+            );
+            continue;
+          }
+          console.log("   \u2714 verified");
+        }
+        setGitHubSecret(repo, env, key, value);
+        const verb = existing?.has(key) ? "overrode" : "pushed";
+        console.log(`   \u2714 ${verb} ${key} \u2192 ${repo}`);
+        pushed++;
+      }
+    }
+  } finally {
+    prompt.close();
+  }
+  console.log(`
+${pushed} secret(s) pushed to ${repo}. (None written to disk.)`);
+}
 async function secretsCommand(args) {
-  if (args[0] !== "sync") {
+  const sub = args[0];
+  if (sub === "gather") {
+    const name = args[1];
+    if (!name || name.startsWith("-")) {
+      throw new Error("usage: greenlight secrets gather <name> [--repo owner/repo] [--env <env>]");
+    }
+    const repo = flag(args, "--repo") ?? detectRepo(process.cwd());
+    if (!repo) throw new Error("could not determine the repo \u2014 pass --repo owner/repo");
+    const ociConfig2 = flag(args, "--oci-config");
+    const ociKey = flag(args, "--oci-key");
+    const prefill = ociConfig2 ? ociPrefill(resolve3(process.cwd(), ociConfig2), ociKey && resolve3(process.cwd(), ociKey)) : void 0;
+    await gatherSecrets(name, repo, flag(args, "--env"), prefill);
+    return;
+  }
+  if (sub !== "sync") {
     console.log(
-      "usage: greenlight secrets sync [--repo owner/repo] [--env <env>]   # push .greenlight/secrets.env to GitHub Actions secrets"
+      "usage:\n  greenlight secrets sync [--repo owner/repo] [--env <env>]            # push .greenlight/secrets.env\n  greenlight secrets gather <name> [--repo owner/repo] [--env <env>]   # guided, link-first, straight to GitHub (no disk/logs)\n    [--oci-config <path>] [--oci-key <path>]                           # auto-fill OCI auth from the API-key config preview + .pem"
     );
-    process.exit(args[0] ? 1 : 0);
+    process.exit(sub ? 1 : 0);
   }
   const { count } = syncSecrets({
     cwd: process.cwd(),
@@ -724,7 +909,7 @@ async function ensureTokensForTool(cwd, tool, opts = {}) {
   const interactive = Boolean(process.stdin.isTTY);
   const env = presentEnv(cwd);
   const results = [];
-  const rl = interactive ? createInterface({ input: process.stdin, output: process.stdout }) : null;
+  const rl = interactive ? createInterface2({ input: process.stdin, output: process.stdout }) : null;
   try {
     for (const spec of tokensForTool(tool)) {
       let value = env[spec.envVar];
@@ -859,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");
@@ -869,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";
@@ -914,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")) {
@@ -1157,7 +1347,6 @@ jobs:
 `;
 }
 function deployListenerYml(name, toolRepo) {
-  const SECRET = `${name.toUpperCase().replace(/-/g, "_")}_OCI_CONTAINER_INSTANCE_OCID`;
   return `name: greenlight-deploy-${name}
 
 # Option B: ${toolRepo} fires repository_dispatch(deploy-${name}) after pushing a new image.
@@ -1177,15 +1366,39 @@ 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:
-          OCI_CLI_USER: \${{ secrets.OCI_CLI_USER }}
-          OCI_CLI_TENANCY: \${{ secrets.OCI_CLI_TENANCY }}
-          OCI_CLI_FINGERPRINT: \${{ secrets.OCI_CLI_FINGERPRINT }}
-          OCI_CLI_KEY_CONTENT: \${{ secrets.OCI_CLI_KEY_CONTENT }}
-          OCI_CLI_REGION: \${{ secrets.OCI_CLI_REGION }}
-          OCI_CONTAINER_INSTANCE_OCID: \${{ secrets.${SECRET} }}
-        run: pnpm exec greenlight deploy ${name} --env prod
+          # 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 }}
+          OCI_CLI_USER: \${{ secrets.TF_VAR_OCI_USER_OCID }}
+          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_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:
@@ -1306,8 +1519,9 @@ Next:
   (in the wrapper) review infra/${name}.tf, then commit the submodule + infra + listener:
     git add .gitmodules ${toolRel} infra/${name}.tf verify/${name}.config.ts greenlight.config.ts .github
     git commit && git push      # CI (infra.yml) applies. Tool's CI builds; wrapper deploys.${target === "oci" ? `
-  Secrets: in ${slug} set GREENLIGHT_DISPATCH_TOKEN; in this wrapper set the OCI_CLI_* creds +
-  ${name.toUpperCase().replace(/-/g, "_")}_OCI_CONTAINER_INSTANCE_OCID (from the TF output) + GREENLIGHT_STATUS_TOKEN.` : ""}`);
+  Secrets (guided): greenlight secrets gather ${name} --repo <wrapper>   # TF_VAR_OCI_* + GREENLIGHT_STATUS_TOKEN
+                    greenlight secrets gather ${name} --repo ${slug}   # GREENLIGHT_DISPATCH_TOKEN
+  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;
@@ -1529,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 });
@@ -1613,7 +1827,7 @@ ${failed === 0 ? "\u2714 no failures" : `\u2718 ${failed} failure(s)`}`);
 // src/commands/init.ts
 import { existsSync as existsSync9, mkdirSync as mkdirSync5, writeFileSync as writeFileSync5 } from "fs";
 import { resolve as resolve8 } from "path";
-import { createInterface as createInterface2 } from "readline/promises";
+import { createInterface as createInterface3 } from "readline/promises";
 function flag5(args, name) {
   const i = args.indexOf(name);
   return i >= 0 ? args[i + 1] : void 0;
@@ -1630,7 +1844,7 @@ async function initCommand(args) {
   let domain = flag5(args, "--domain");
   if (!domain) {
     if (!process.stdin.isTTY) throw new Error("init needs --domain <domain> (no TTY for prompts)");
-    const rl = createInterface2({ input: process.stdin, output: process.stdout });
+    const rl = createInterface3({ input: process.stdin, output: process.stdout });
     domain = (await rl.question("Domain (e.g. example.dev): ")).trim();
     rl.close();
   }
@@ -1901,6 +2115,7 @@ var HELP = `greenlight <command>
   preview <name> [--port <n>]                   build + serve locally + verify (one command)
   verify <name> [--env <env> | --url <url>]     run the verify harness against the URL
   promote <name> [--perform] [--push]           gated develop -> main fast-forward
+  secrets gather <name> [--repo o/r] [--env e]  guided, link-first token prompts -> GitHub secrets (no disk/logs)
   secrets sync [--repo o/r] [--env <env>]       push .greenlight/secrets.env -> GitHub Actions secrets
   agent sync                                    write the loop skill + CLAUDE.md block into this repo
   adopt <name> --repo <path> --lane --target    onboard an existing tool repo as a thin consumer

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.4",
+  "version": "0.2.6",
   "description": "Greenlight CLI — setup and lifecycle for the harness.",
   "license": "MIT",
   "repository": {