@valescoagency/runway 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Valesco Agency
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,199 @@
+# runway
+
+A small CLI for two jobs: **scaffold** a target repo for autonomous
+coding-agent runs, then **drain** a Linear queue against it. Wraps
+[Sandcastle](https://github.com/mattpocock/sandcastle) (Claude Code
+inside Docker), [varlock](https://varlock.dev) + 1Password for
+zero-secrets-at-rest, and the `gh` CLI for PR creation.
+
+## Five commands
+
+| | |
+|---|---|
+| `runway doctor` | Read-only preflight diagnostic: host tooling, env vars, repo state, and the agent docker image. Use when something stopped working and you want a sanity report. `--json` for CI / scripted health checks. |
+| `runway init` | Scaffold the cwd repo for runway: write `.sandcastle/Dockerfile` + (tier 2) `.env.schema` with op:// references. Run **once per target repo**. |
+| `runway run` | Drain a Linear queue. For each `Todo` issue: branch, agent works, sub-agent reviews, PR opens (or `needs-human` label). Run **whenever you want a batch of work done**. |
+| `runway upgrade` | Update the runway CLI itself: `git pull` the local clone, `pnpm install`, typecheck. `--check` for a dry-run, `--force` to override dirty/branch refusals. |
+| `runway upgrade-repo` | Re-render the cwd repo's runway scaffold against the current vendored templates. Use after a runway version bump that changed the Dockerfile or template shape — `init` writes them, `upgrade-repo` keeps them current without re-prompting for op:// values. |
+
+`runway --help` for the full usage; `runway <cmd> --help` per command.
+
+`runway init` and `runway upgrade-repo` are siblings: `init` is the
+first-time scaffold (you provide the op:// vault/items), `upgrade-repo`
+is the re-render (extracts those values from the existing `.env.schema`
+so you never re-type them). Override the extracted values via
+`--op-vault=…`, `--anthropic-item=…`, `--gh-token-item=…` if needed,
+or use `--check` for a CI dry-run that exits 1 on drift.
+
+## What runway is and isn't
+
+| It is | It isn't |
+|---|---|
+| A small Node CLI that orchestrates Sandcastle runs from a Linear queue | A sandbox or agent runtime — Sandcastle does that |
+| The replacement for the AFK label-handler / preflight / contracts pipeline | A governance layer; trust comes from your review of the PR, not gates |
+| Repo-agnostic — runs in whatever cwd you launch it from | Multi-repo (yet) — one repo per `runway run` invocation |
+| Sequential | Parallel (yet) |
+
+## Architecture
+
+```
+Linear (Todo, team=VA)
+  ↓ poll
+runway (this CLI, on your Mac, run from inside the target repo)
+  ↓ for each issue
+  │   sandcastle.run({ agent: claudeCode, sandbox: docker, cwd: process.cwd(), ... })
+  │   → branch agent/<issue-id>, commits, tests
+  │
+  │   sandcastle.run({ ..., prompt: review template })
+  │   → REVIEW: APPROVED  | REVIEW: REJECTED — <reason>
+  │
+  ├── approved  → git push → gh pr create → Linear "In Review"
+  └── rejected  → Linear label "needs-human", comment with reason
+  ↓ next issue
+```
+
+## Prerequisites
+
+- macOS or Linux
+- Docker Desktop (or Podman)
+- Node 22+
+- `gh` CLI authenticated against the org that hosts your target repo
+- Linear API key with read+write on the team you're targeting
+- Anthropic API key (set in the **target repo's** `.sandcastle/.env`,
+  not in runway's env — Sandcastle reads it)
+
+## One-time setup per target repo
+
+```bash
+cd /path/to/your/repo
+runway init \
+  --op-vault=runway \
+  --anthropic-item=anthropic-api-key \
+  --gh-token-item=gh-token
+```
+
+(No `--op-account` — runway uses 1Password service-account auth
+(`OP_SERVICE_ACCOUNT_TOKEN`) exclusively, and the token already
+encodes the tenant. `op://` URIs runway writes are
+`op://<vault>/<item>`, not `op://<account>/<vault>/<item>`.)
+
+This runs `npx sandcastle init`, patches the generated `.sandcastle/Dockerfile`
+to bake in `varlock` + the 1Password CLI + a `claude` shim, scaffolds
+`.env.schema` at the repo root with op:// references to your 1Password vault,
+and deletes `.sandcastle/.env` so no secrets sit at rest. Review the diff,
+commit on a feature branch, open a PR.
+
+Pass `--tier=1` if you want the plain Sandcastle setup with `.sandcastle/.env`
+and no varlock (faster but secrets land on disk).
+
+Architecture walkthrough: [`docs/secrets-with-varlock.md`](docs/secrets-with-varlock.md).
+
+## Secrets — recommended: varlock + 1Password
+
+If you don't want any secret sitting at rest in any `.env` file,
+runway integrates [varlock](https://varlock.dev). Two layers (host +
+in-container), both opt-in. Full walk-through:
+[`docs/secrets-with-varlock.md`](docs/secrets-with-varlock.md).
+
+TL;DR for the host layer:
+
+```bash
+varlock run --schema /path/to/runway/.env.schema -- runway --max 3
+```
+
+Without varlock, runway falls back to plain `process.env` and
+sandcastle reads `.sandcastle/.env` per its docs.
+
+## Install
+
+```bash
+pnpm install -g @valescoagency/runway       # or npm i -g, yarn global add
+```
+
+Export runway's own env (in your shell rc, or wherever you keep API keys):
+
+```bash
+export LINEAR_API_KEY=lin_api_...
+# Optional overrides:
+# export RUNWAY_LINEAR_TEAM=VA
+# export RUNWAY_READY_STATUS="Todo"
+# export RUNWAY_IN_PROGRESS_STATUS="In Progress"
+# export RUNWAY_IN_REVIEW_STATUS="In Review"
+# export RUNWAY_HITL_LABEL="needs-human"
+# export RUNWAY_MAX_ITERATIONS=5
+```
+
+### From source (development)
+
+```bash
+git clone git@github.com:ValescoAgency/runway.git
+cd runway
+pnpm install
+pnpm build              # compiles src/ → dist/
+pnpm link --global      # so `runway` is on your $PATH
+```
+
+`pnpm dev -- <args>` runs the TypeScript source via `tsx` without building, useful while iterating on runway itself.
+
+## Usage
+
+```bash
+cd /path/to/the/repo/you/want/agents/working/on
+runway run             # drain the entire ready queue
+runway run --max 3     # process at most 3 issues then exit
+runway --help
+```
+
+`runway` (no subcommand) is an alias for `runway run` for back-compat.
+
+The CLI exits with 0 even if some issues hit HITL or errored — those
+are normal outcomes. Check Linear for the `needs-human` label and the
+per-issue comments for what happened.
+
+## Linear conventions
+
+Runway picks up issues that are:
+
+- in team `RUNWAY_LINEAR_TEAM` (default `VA`)
+- in workflow state `RUNWAY_READY_STATUS` (default `Todo`)
+
+It transitions them through:
+
+- `In Progress` while the agent is running
+- `In Review` when the PR opens
+- (label `needs-human`) if the agent or reviewer can't finish
+
+These names are configurable per env var; the queries match by name so
+your Linear workspace's actual state names need to line up with what
+you set.
+
+## Sub-agent review
+
+Every implementation run is followed by a fresh Sandcastle run with
+[`prompts/review.md`](prompts/review.md). The reviewer reads the diff
+and the issue body and outputs one of:
+
+```
+REVIEW: APPROVED
+REVIEW: REJECTED — <one-line reason>
+```
+
+If approved, runway pushes the branch and opens the PR. If rejected,
+the issue gets the HITL label and a comment with the reviewer's reason.
+
+The reviewer is intentionally adversarial — its job is to find reasons
+NOT to ship, not to rubber-stamp.
+
+## What's deliberately missing in v1
+
+- Parallel runs (one issue at a time)
+- Multi-repo dispatch from a single command (cd into each repo)
+- Vercel Sandbox provider (Docker only — swap to `vercel()` later)
+- DAG / dependency awareness across issues
+- Auto-rebase / merge of approved PRs (you do that)
+
+These are tractable, just not v1.
+
+## Status
+
+v0.1 — scaffold complete, untested against a live queue.

package/dist/cli.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import { doctorCommand, printDoctorUsage } from "./commands/doctor.js";
+import { initCommand, printInitUsage } from "./commands/init.js";
+import { runCommand, printRunUsage } from "./commands/run.js";
+import { upgradeCommand, printUpgradeUsage } from "./commands/upgrade.js";
+import { upgradeRepoCommand, printUpgradeRepoUsage, } from "./commands/upgrade-repo.js";
+const SUBCOMMANDS = [
+    {
+        name: "doctor",
+        summary: "Read-only preflight: tooling, env, repo state, agent image.",
+        run: doctorCommand,
+        help: printDoctorUsage,
+    },
+    {
+        name: "init",
+        summary: "Scaffold a target repo (sandcastle init + varlock layer).",
+        run: initCommand,
+        help: printInitUsage,
+    },
+    {
+        name: "run",
+        summary: "Drain a Linear queue against the cwd repo (default verb).",
+        run: runCommand,
+        help: printRunUsage,
+    },
+    {
+        name: "upgrade",
+        summary: "Update the runway CLI itself (git pull + pnpm install).",
+        run: upgradeCommand,
+        help: printUpgradeUsage,
+    },
+    {
+        name: "upgrade-repo",
+        summary: "Refresh a target repo's runway scaffold against current templates.",
+        run: upgradeRepoCommand,
+        help: printUpgradeRepoUsage,
+    },
+];
+function printRootUsage() {
+    console.log(`runway — Linear-driven coding agent orchestrator
+
+USAGE
+  runway <command> [options]
+
+COMMANDS`);
+    for (const cmd of SUBCOMMANDS) {
+        console.log(`  ${cmd.name.padEnd(13)} ${cmd.summary}`);
+    }
+    console.log(`
+  Run \`runway <command> --help\` for command-specific options.
+
+GLOBAL
+  --help, -h     Show this help.
+  --version, -V  Show version.
+`);
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
+        printRootUsage();
+        process.exit(0);
+    }
+    if (argv[0] === "--version" || argv[0] === "-V") {
+        // Read package.json at runtime — single source of truth.
+        const { readFile } = await import("node:fs/promises");
+        const { fileURLToPath } = await import("node:url");
+        const { dirname, join } = await import("node:path");
+        const here = dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(await readFile(join(here, "..", "package.json"), "utf8"));
+        console.log(pkg.version);
+        process.exit(0);
+    }
+    // First arg may be a subcommand name. If it isn't, treat the whole
+    // argv as `run <argv>` (back-compat: `runway --max 3` still works).
+    const first = argv[0];
+    const matched = SUBCOMMANDS.find((c) => c.name === first);
+    if (matched) {
+        await matched.run(argv.slice(1));
+    }
+    else {
+        // Implicit `run` — back-compat for old invocations.
+        await runCommand(argv);
+    }
+}
+main().catch((err) => {
+    console.error("[runway] fatal:", err instanceof Error ? err.message : err);
+    process.exit(1);
+});