@codyswann/lisa 2.316.2 → 2.317.0

package/plugins/lisa/.codex-plugin/skills/lisa-secrets-access/scripts/surfaces.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+/**
+ * Surface definitions and configuration for `lisa-secrets-access`.
+ *
+ * A *provider* is where secrets live. A *surface* is where the running code
+ * lives, and it determines how secrets reach that code. These are independent
+ * axes: the same Bitwarden project serves a laptop, a CI runner, and a remote
+ * agent container, but each of the three obtains its values differently.
+ *
+ * Surfaces are declared by capability rather than by name so adding one is a
+ * single entry here rather than a new branch in every consumer. That is the
+ * whole reason this table exists.
+ * @module surfaces
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Capabilities, per surface.
+ *
+ * `materialized` — the surface obtains values from files written before the
+ * code ran, so the resolver must consult them.
+ *
+ * `mayWriteValues` — the surface is permitted to write resolved values to
+ * disk. This is normally forbidden, because a value on disk is a copy that can
+ * drift and leak. It is *required* on surfaces whose bootstrap runs before the
+ * consuming process exists and which therefore have no other channel; a remote
+ * agent container prepares itself during setup, long before any task starts.
+ */
+export const SURFACES = {
+  local: { materialized: false, mayWriteValues: false },
+  "github-actions": { materialized: false, mayWriteValues: false },
+  "codex-cloud": { materialized: true, mayWriteValues: true },
+};
+
+/** Config defaults when `.lisa.config.json` carries no `secrets` block. */
+const DEFAULTS = {
+  provider: "env",
+  bootstrap: { sources: ["env"], key: null },
+  require: null,
+  rotating: [],
+  namespace: "lisa",
+  narrow: { projectIds: [], excludeKeys: [] },
+  surface: null,
+};
+
+/**
+ * Identify the surface this process is running on.
+ *
+ * An explicit value always wins, so an operator can reproduce another
+ * surface's behaviour locally when diagnosing one. Detection is otherwise
+ * ordered most-specific first.
+ * @param {string|null} [configured] Surface named in `.lisa.config.json`.
+ * @param {Record<string, string|undefined>} [env] Environment to inspect.
+ * @returns {string} A key of {@link SURFACES}.
+ */
+export function detectSurface(configured = null, env = process.env) {
+  const explicit = (env.LISA_SECRETS_SURFACE ?? "").trim() || configured;
+  if (explicit) {
+    if (!SURFACES[explicit]) {
+      throw new Error(
+        `unknown surface "${explicit}".\n` +
+          `Known: ${Object.keys(SURFACES).join(", ")}`
+      );
+    }
+    return explicit;
+  }
+  if ((env.GITHUB_ACTIONS ?? "") === "true") return "github-actions";
+  if ((env.CODEX_SANDBOX ?? env.CODEX_HOME ?? "") !== "") return "codex-cloud";
+  return "local";
+}
+
+/**
+ * Reject a namespace that is not exactly one safe path segment.
+ *
+ * The namespace is joined onto a config root, so anything containing a
+ * separator or a parent reference could redirect writes outside the intended
+ * directory. Validating here means every caller inherits the guard.
+ * @param {string} namespace Candidate namespace.
+ * @returns {string} The namespace, unchanged, when valid.
+ */
+export function assertNamespace(namespace) {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(namespace) || namespace === "..") {
+    throw new Error(
+      `secrets.namespace must be one safe path segment, got "${namespace}"`
+    );
+  }
+  return namespace;
+}
+
+/**
+ * Where a surface's materialized files live.
+ * @param {string} namespace Validated namespace.
+ * @param {Record<string, string|undefined>} [env] Environment to inspect.
+ * @returns {{dir: string, valuesFile: string, notesFile: string}} Paths.
+ */
+export function materializedPaths(namespace, env = process.env) {
+  const root = env.XDG_CONFIG_HOME || join(env.HOME || homedir(), ".config");
+  const dir = join(root, assertNamespace(namespace));
+  return {
+    dir,
+    valuesFile: join(dir, "secrets.env"),
+    notesFile: join(dir, "secret-notes.json"),
+  };
+}
+
+/**
+ * Read the `secrets` block from `.lisa.config.json`.
+ *
+ * A project with no block is a supported state, not an error: the `env`
+ * provider means the environment *is* the provider. A credentials manager is
+ * the preferred path, never a required one.
+ * @param {string} [cwd] Directory to look in.
+ * @returns {object} Resolved configuration with defaults applied.
+ */
+export function readConfig(cwd = process.cwd()) {
+  const path = join(cwd, ".lisa.config.json");
+  if (!existsSync(path)) return withSurface(DEFAULTS);
+  let cfg;
+  try {
+    cfg = JSON.parse(readFileSync(path, "utf8")).secrets;
+  } catch (err) {
+    throw new Error(`.lisa.config.json is not readable: ${err.message}`);
+  }
+  if (!cfg) return withSurface(DEFAULTS);
+  return withSurface({
+    provider: cfg.provider ?? DEFAULTS.provider,
+    bootstrap: { ...DEFAULTS.bootstrap, ...(cfg.bootstrap ?? {}) },
+    require: cfg.require ?? null,
+    rotating: cfg.rotating ?? [],
+    namespace: assertNamespace(cfg.namespace ?? DEFAULTS.namespace),
+    narrow: { ...DEFAULTS.narrow, ...(cfg.narrow ?? {}) },
+    surface: cfg.surface ?? null,
+  });
+}
+
+/**
+ * Attach the resolved surface and its capabilities to a configuration.
+ * @param {object} cfg Configuration without surface resolution.
+ * @returns {object} The same configuration plus `surface` and `capabilities`.
+ */
+function withSurface(cfg) {
+  const surface = detectSurface(cfg.surface);
+  return { ...cfg, surface, capabilities: SURFACES[surface] };
+}

package/plugins/lisa/.codex-plugin/skills/lisa-secrets-access/scripts/validate-config.mjs

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+/**
+ * Validate the `secrets`, `remoteEnv`, and `automations` blocks.
+ *
+ * These blocks are read by shell, by Node, and by generated workflows, so a
+ * malformed one surfaces late and somewhere unhelpful — a container that fails
+ * mid-setup, a scheduled loop that never fires, a dispatch that names a surface
+ * nobody provisioned. Checking the shape up front turns all of those into one
+ * message at `doctor` time.
+ *
+ * Structure only. Whether a credential resolves is `doctor-secrets.mjs`; this
+ * asks whether the declaration could ever be correct.
+ *
+ * Usage:
+ *   validate-config.mjs
+ * @module validate-config
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** Providers with a read implementation today. */
+const IMPLEMENTED_PROVIDERS = new Set(["bitwarden", "doppler", "env"]);
+
+/** Providers named in the dispatch table but not yet implemented. */
+const DECLARED_PROVIDERS = new Set(["1password", "aws", "vault"]);
+
+/** Surfaces the resolver knows. */
+const SURFACES = new Set(["local", "github-actions", "codex-cloud"]);
+
+/** Install methods the toolchain runner supports. */
+const INSTALL_METHODS = new Set(["release-zip", "npm-global"]);
+
+/**
+ * Validate the `secrets` block.
+ * @param {object|undefined} secrets The block, if present.
+ * @returns {string[]} Problems found.
+ */
+export function validateSecrets(secrets) {
+  if (!secrets) return [];
+  const problems = [];
+  const provider = secrets.provider ?? "env";
+
+  if (DECLARED_PROVIDERS.has(provider)) {
+    problems.push(
+      `secrets.provider "${provider}" is documented but has no read ` +
+        `implementation yet. Add one in providers.mjs rather than configuring it.`
+    );
+  } else if (!IMPLEMENTED_PROVIDERS.has(provider)) {
+    problems.push(
+      `secrets.provider "${provider}" is unknown. ` +
+        `Known: ${[...IMPLEMENTED_PROVIDERS, ...DECLARED_PROVIDERS].join(", ")}.`
+    );
+  }
+
+  if (
+    secrets.namespace &&
+    !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(secrets.namespace)
+  ) {
+    problems.push(
+      `secrets.namespace "${secrets.namespace}" is not one safe path segment. ` +
+        `It is joined onto a config root, so a separator could redirect writes.`
+    );
+  }
+
+  if (secrets.surface && !SURFACES.has(secrets.surface)) {
+    problems.push(
+      `secrets.surface "${secrets.surface}" is unknown. ` +
+        `Known: ${[...SURFACES].join(", ")}.`
+    );
+  }
+
+  for (const field of ["require", "rotating"]) {
+    const value = secrets[field];
+    if (value === undefined || value === null) continue;
+    if (!Array.isArray(value)) {
+      problems.push(`secrets.${field} must be an array of exact key names`);
+      continue;
+    }
+    for (const name of value) {
+      if (typeof name !== "string" || !/^[A-Z][A-Z0-9_]*$/.test(name)) {
+        problems.push(
+          `secrets.${field} entry ${JSON.stringify(name)} is not an exact ` +
+            `UPPER_SNAKE_CASE environment-variable name. Lookup is never fuzzy.`
+        );
+      }
+    }
+  }
+
+  if ((secrets.rotating ?? []).length && !secrets.bootstrap?.key) {
+    problems.push(
+      `secrets.rotating is declared but secrets.bootstrap.key is not. A ` +
+        `rotating credential whose replacement cannot be written back is ` +
+        `stranded the first time it is used.`
+    );
+  }
+
+  return problems;
+}
+
+/**
+ * Validate the `remoteEnv` block.
+ * @param {object|undefined} remoteEnv The block, if present.
+ * @returns {string[]} Problems found.
+ */
+export function validateRemoteEnv(remoteEnv) {
+  if (!remoteEnv) return [];
+  const problems = [];
+
+  for (const tool of remoteEnv.tools?.require ?? []) {
+    if (!tool.name) problems.push("remoteEnv.tools.require entry has no name");
+  }
+  for (const tool of remoteEnv.tools?.install ?? []) {
+    if (!tool.name) {
+      problems.push("remoteEnv.tools.install entry has no name");
+      continue;
+    }
+    if (!tool.version) {
+      problems.push(`remoteEnv install "${tool.name}" has no pinned version`);
+    }
+    if (!INSTALL_METHODS.has(tool.install)) {
+      problems.push(
+        `remoteEnv install "${tool.name}" has method ${JSON.stringify(tool.install)}. ` +
+          `Supported: ${[...INSTALL_METHODS].join(", ")}.`
+      );
+      continue;
+    }
+    if (tool.install === "release-zip" && !(tool.url && tool.sha256)) {
+      problems.push(
+        `remoteEnv install "${tool.name}" needs both url and sha256. A pinned ` +
+          `version with no checksum still trusts whatever the URL serves today.`
+      );
+    }
+    if (tool.install === "npm-global" && !tool.package) {
+      problems.push(`remoteEnv install "${tool.name}" needs a package`);
+    }
+  }
+
+  for (const [surface, block] of Object.entries(remoteEnv.surfaces ?? {})) {
+    if (!SURFACES.has(surface)) {
+      problems.push(`remoteEnv.surfaces has unknown surface "${surface}"`);
+    }
+    if (!block.repository) {
+      problems.push(`remoteEnv.surfaces["${surface}"] has no repository`);
+    }
+  }
+
+  return problems;
+}
+
+/**
+ * Validate the `automations` block against declared surfaces.
+ * @param {object|undefined} automations The block, if present.
+ * @param {object|undefined} remoteEnv The remote-environment block.
+ * @returns {string[]} Problems found.
+ */
+export function validateAutomations(automations, remoteEnv) {
+  if (!automations) return [];
+  const problems = [];
+
+  for (const [name, loop] of Object.entries(automations)) {
+    if (loop.scheduler !== "github-actions") continue;
+    if (!loop.schedule) {
+      problems.push(`automations["${name}"] has no schedule`);
+    }
+    if (!loop.executionEnv) {
+      problems.push(`automations["${name}"] has no executionEnv`);
+      continue;
+    }
+    if (!SURFACES.has(loop.executionEnv)) {
+      problems.push(
+        `automations["${name}"].executionEnv "${loop.executionEnv}" is unknown`
+      );
+      continue;
+    }
+    if (!remoteEnv?.surfaces?.[loop.executionEnv]?.repository) {
+      problems.push(
+        `automations["${name}"] dispatches to "${loop.executionEnv}", which is ` +
+          `not provisioned. Run /lisa:setup:remote-env ${loop.executionEnv} first.`
+      );
+    }
+  }
+
+  return problems;
+}
+
+/**
+ * Validate every block this plan introduced.
+ * @param {object} cfg Parsed `.lisa.config.json`.
+ * @returns {string[]} Problems found.
+ */
+export function validateConfig(cfg) {
+  return [
+    ...validateSecrets(cfg.secrets),
+    ...validateRemoteEnv(cfg.remoteEnv),
+    ...validateAutomations(cfg.automations, cfg.remoteEnv),
+  ];
+}
+
+function main() {
+  const path = join(process.cwd(), ".lisa.config.json");
+  if (!existsSync(path)) {
+    console.log("no .lisa.config.json — nothing to validate");
+    return;
+  }
+  const problems = validateConfig(JSON.parse(readFileSync(path, "utf8")));
+  if (!problems.length) {
+    console.log(
+      "config: secrets, remoteEnv and automations blocks are well-formed"
+    );
+    return;
+  }
+  for (const problem of problems) console.error(`  ${problem}`);
+  throw new Error(`${problems.length} configuration problem(s)`);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  try {
+    main();
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+}

package/plugins/lisa/.codex-plugin/skills/lisa-setup-automations/SKILL.md

@@ -26,6 +26,75 @@ create them; invoke the runtime's automation tool with the spec below.
 - **Other runtimes** → use the runtime's native recurring-task mechanism. If the runtime has none,
   state that scheduling is unavailable and stop.
 
+## Unattended scheduling: `scheduler: "github-actions"`
+
+Every option above runs on the **workstation**. That is correct when the operator is present, and
+useless when the goal is "fire work off, close the laptop, go to sleep" — a native automation on a
+sleeping machine does not fire.
+
+When a loop declares `scheduler: "github-actions"`, generate a workflow instead of a local routine.
+This is the right shape only in combination with `executionEnv`: the scheduled job becomes a **thin
+dispatcher** that wakes, picks eligible work, submits it to a remote surface, records the identifier,
+and exits. The heavy lifting happens on the remote surface, so the clock needs availability rather
+than power.
+
+```json
+{
+  "automations": {
+    "intake": {
+      "scheduler": "github-actions",
+      "schedule": "17 * * * *",
+      "executionEnv": "codex-cloud",
+      "enabled": false
+    }
+  }
+}
+```
+
+`scheduler` is the pluggable seam. The same declaration generates a GitHub Actions workflow today and
+can register a different mechanism later without touching the loop itself. **Config is the source of
+truth; the workflow is generated from it** — regenerate rather than hand-edit.
+
+```sh
+scripts/generate-workflow.mjs intake --write
+```
+
+### Why GitHub Actions is the default unattended clock
+
+It is already present in every host project, already holds the bootstrap credential, and provides
+cron, concurrency groups, retries, manual dispatch, and an audit trail. Cost is negligible: billing is
+per minute rounded up, and a dispatch-only job finishes in well under one — a nightly loop runs a few
+dollars a year. Note the rounding is **per workflow run**, so batching N dispatches into one run is
+far cheaper than N triggers.
+
+The real cost is the remote task's own consumption, against which the clock is a rounding error.
+
+Rejected: workstation-native automation mechanisms for this purpose — they reintroduce exactly the
+sleeping-laptop problem this option exists to solve.
+
+### Registered disabled
+
+A recurring trigger goes live **only after the exact production path has been proven once for one
+real item.** Registration therefore writes a `workflow_dispatch`-only workflow; enabling adds the
+cron. The generator says so when it writes a disabled loop.
+
+**GitHub auto-disables scheduled workflows after 60 days of repository inactivity.** For an
+unattended factory that is a real trap — a quiet repository silently stops running its loops, and
+nothing announces it. `lisa-automation-status` must treat a stopped clock as a finding.
+
+### What the generated workflow guarantees
+
+- **Never cancels in progress.** Cancelling could kill a dispatch after the remote accepted a task
+  but before its identifier was recorded — irreversible work with nothing to reconcile against, where
+  a retry duplicates it.
+- **Asserts the bootstrap before installing anything**, so a misconfigured secret fails in seconds
+  rather than after a toolchain download.
+- **Persists credential rotation with `if: always()`.** The dispatcher authenticates with a
+  credential that rotates on use, so the replacement must be written back even when the dispatch
+  itself failed. That makes the very first artifact this produces an exercise of the rotating-credential
+  path in `lisa-secrets-access`, not a hypothetical one.
+- **Guards on the repository**, so a fork does not inherit a live clock.
+
 ## Parameters
 
 - `auto-start-prds` (default **true**) — passed as `prd_ready` to the **exploratory-prds**

package/plugins/lisa/.codex-plugin/skills/lisa-setup-automations/scripts/generate-workflow.mjs

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+/**
+ * Generate the GitHub Actions workflow that fires a registered automation loop.
+ *
+ * Once `executionEnv` exists, a scheduled loop is a thin dispatcher: it wakes,
+ * picks eligible work, submits it to a remote surface, records the identifier,
+ * and exits. The heavy lifting happens elsewhere. That makes the clock's job
+ * cheap and boring, and the requirements on it are availability rather than
+ * power.
+ *
+ * The workflow is generated from `.lisa.config.json` rather than hand-written,
+ * so config stays the source of truth and swapping the scheduler later is a
+ * config change instead of a rewrite.
+ *
+ * Usage:
+ *   generate-workflow.mjs <loop-name> [--write]
+ * @module generate-workflow
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/** Where a generated loop workflow lands. */
+export const workflowPath = name =>
+  join(".github", "workflows", `lisa-${name}.yml`);
+
+/**
+ * Read one automation's declaration.
+ * @param {string} name Loop name.
+ * @param {string} [cwd] Repository root.
+ * @returns {object} The loop's configuration.
+ */
+export function readAutomation(name, cwd = process.cwd()) {
+  const path = join(cwd, ".lisa.config.json");
+  if (!existsSync(path)) throw new Error(".lisa.config.json is missing");
+  const cfg = JSON.parse(readFileSync(path, "utf8"));
+  const loop = cfg.automations?.[name];
+  if (!loop) {
+    throw new Error(
+      `no automations["${name}"] in .lisa.config.json.\n` +
+        `Declare the loop before generating its workflow.`
+    );
+  }
+  return {
+    ...loop,
+    repository: cfg.remoteEnv?.surfaces?.[loop.executionEnv]?.repository,
+  };
+}
+
+/**
+ * Render the workflow YAML for one loop.
+ *
+ * Three choices here are load-bearing rather than stylistic.
+ *
+ * The `schedule` trigger is emitted **only when the loop is enabled**. A
+ * recurring trigger goes live after the exact production path has been proven
+ * once for one real item, so registration writes a manually-dispatchable
+ * workflow and enabling adds the clock.
+ *
+ * The concurrency group **never cancels in progress**. Cancelling could kill a
+ * dispatch after the remote accepted a task but before its identifier was
+ * recorded, which orphans irreversible work — nothing left to reconcile against,
+ * and a retry that duplicates it.
+ *
+ * The bootstrap credential is asserted **before** anything is installed, so a
+ * misconfigured secret fails in seconds rather than after a toolchain download.
+ * @param {string} name Loop name.
+ * @param {object} loop Loop configuration.
+ * @returns {string} Workflow YAML.
+ */
+export function renderWorkflow(name, loop) {
+  if (!loop.schedule) throw new Error(`automations["${name}"] has no schedule`);
+  if (!loop.repository) {
+    throw new Error(
+      `automations["${name}"] targets executionEnv "${loop.executionEnv}", ` +
+        `but no remoteEnv.surfaces["${loop.executionEnv}"].repository is set.\n` +
+        `Run /lisa:setup:remote-env ${loop.executionEnv} first.`
+    );
+  }
+
+  const trigger = loop.enabled
+    ? `  schedule:\n    - cron: '${loop.schedule}'\n  workflow_dispatch:`
+    : `  # schedule: disabled until the production path is proven once for one\n` +
+      `  # real item. Enabling adds:  - cron: '${loop.schedule}'\n  workflow_dispatch:`;
+
+  return `# Generated by lisa-setup-automations from .lisa.config.json.
+# Edit the config and regenerate; hand edits are overwritten.
+name: 🔁 Lisa ${name}
+
+on:
+${trigger}
+
+# Never cancel in progress. A cancelled dispatch can leave a remote task that
+# was accepted but whose identifier was never recorded — irreversible work with
+# nothing to reconcile against, where a retry duplicates it.
+concurrency:
+  group: lisa-${name}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  dispatch:
+    name: Dispatch one ${name} cycle
+    if: github.repository == '${loop.repository}'
+    runs-on: ubuntu-latest
+    timeout-minutes: ${loop.timeoutMinutes ?? 15}
+    env:
+      LISA_SECRETS_SURFACE: github-actions
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      # Assert first, install second: a misconfigured bootstrap should fail in
+      # seconds rather than after a toolchain download.
+      - name: Check the bootstrap credential is configured
+        env:
+          BWS_ACCESS_TOKEN: \${{ secrets.BWS_ACCESS_TOKEN }}
+        run: |
+          set -euo pipefail
+          test -n "\${BWS_ACCESS_TOKEN}" || {
+            echo "BWS_ACCESS_TOKEN is not configured for this repository" >&2
+            exit 1
+          }
+
+      - name: Prepare the toolchain and secrets
+        env:
+          BWS_ACCESS_TOKEN: \${{ secrets.BWS_ACCESS_TOKEN }}
+        run: bash scripts/lisa-remote-env/setup.sh
+
+      - name: Run one ${name} cycle
+        env:
+          BWS_ACCESS_TOKEN: \${{ secrets.BWS_ACCESS_TOKEN }}
+        run: |
+          set -euo pipefail
+          node .claude/skills/lisa-remote-dispatch/scripts/dispatch.mjs \\
+            'executionEnv=${loop.executionEnv} ${loop.payload ?? ""}' \\
+            --skill ${loop.skill ?? `lisa-${name}`}
+
+      # The dispatcher authenticates with a credential that rotates on use, so
+      # the replacement must be persisted even when the dispatch itself failed.
+      - name: Persist any credential rotation
+        if: \${{ always() }}
+        env:
+          BWS_ACCESS_TOKEN: \${{ secrets.BWS_ACCESS_TOKEN }}
+        run: |
+          set -euo pipefail
+          node .claude/skills/lisa-secrets-access/scripts/rotate-secret.mjs leases
+`;
+}
+
+function main() {
+  const [name, ...flags] = process.argv.slice(2);
+  if (!name)
+    throw new Error("usage: generate-workflow.mjs <loop-name> [--write]");
+  const loop = readAutomation(name);
+  const yaml = renderWorkflow(name, loop);
+
+  if (!flags.includes("--write")) {
+    process.stdout.write(yaml);
+    return;
+  }
+  const path = workflowPath(name);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, yaml);
+  console.log(`wrote ${path}`);
+  if (!loop.enabled) {
+    console.log(
+      "Registered DISABLED. Prove the exact production path once for one real " +
+        "item with a manual dispatch, then set enabled: true and regenerate."
+    );
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  try {
+    main();
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+}