ghostrail 0.4.0 → 0.6.0

package/dist/secrets/setup.js

@@ -0,0 +1,124 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { parseEnvFile } from "./env-file.js";
+import { DEFAULT_FORWARD_ENV } from "./known.js";
+/** The secrets file holds credentials, so it is created owner-only. */
+export const SECRETS_FILE_MODE = 0o600;
+/** The global config dir, created owner-only for the same reason. */
+export const SECRETS_DIR_MODE = 0o700;
+/**
+ * What each credential is for. Keyed by {@link CredentialKey}, so adding a name
+ * to `DEFAULT_FORWARD_ENV` without describing it here is a type error rather
+ * than a key silently missing from the scaffolded file.
+ */
+const DESCRIPTIONS = {
+    ANTHROPIC_API_KEY: "Anthropic API key. Bills metered API usage, and wins over CLAUDE_CODE_OAUTH_TOKEN when both are set.",
+    CLAUDE_CODE_OAUTH_TOKEN: "From `claude setup-token`. Bills a Claude Pro/Max subscription; leave ANTHROPIC_API_KEY unset to use it.",
+    GH_TOKEN: "GitHub token with repo + pull-request write. Used to push factory branches and open PRs.",
+    GITHUB_TOKEN: "Alternative name for the GitHub token, read when GH_TOKEN is unset.",
+    LINEAR_API_KEY: "Linear personal API key (Settings > Security & Access). Required for every run.",
+};
+/** Every credential ghostrail reads, in forwarding order. */
+export const KNOWN_SECRETS = DEFAULT_FORWARD_ENV.map((key) => ({
+    key,
+    description: DESCRIPTIONS[key],
+}));
+/**
+ * A commented placeholder line: a comment whose first content is `KEY=`, with an
+ * optional `export`. Requiring the `=` is what separates a placeholder from
+ * prose that merely names a variable.
+ */
+const COMMENTED_ASSIGNMENT = /^#+\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/;
+/**
+ * The variable names the content refers to, whether as a live assignment or as a
+ * commented placeholder. Both count, so topping a file up never re-adds a
+ * placeholder the file already carries.
+ *
+ * Only names are returned. No value is read, returned, or surfaced.
+ */
+export function mentionedKeys(content) {
+    const keys = new Set(Object.keys(parseEnvFile(content)));
+    for (const rawLine of content.split("\n")) {
+        const line = rawLine.trim();
+        if (!line.startsWith("#"))
+            continue;
+        const match = COMMENTED_ASSIGNMENT.exec(line);
+        const key = match?.[1];
+        if (key !== undefined)
+            keys.add(key);
+    }
+    return keys;
+}
+/**
+ * The known credentials the content does not mention, in `KNOWN_SECRETS` order.
+ * `undefined` content (no file yet) means every one of them is missing. Names
+ * the file carries that ghostrail does not read are ignored.
+ */
+export function missingSecrets(content) {
+    if (content === undefined)
+        return [...KNOWN_SECRETS];
+    const mentioned = mentionedKeys(content);
+    return KNOWN_SECRETS.filter((spec) => !mentioned.has(spec.key));
+}
+const HEADER = [
+    "# ghostrail credentials.",
+    "#",
+    "# ghostrail reads this file on every run, watch, respond, and triage. A value",
+    "# set here overrides the same variable in your environment (precedence: a",
+    "# repo's .ghostrail.env, then this file, then the ambient environment).",
+    "#",
+    "# Uncomment a line and fill in the value. Leave the rest commented: an",
+    "# uncommented empty value would blank out a working credential from your",
+    "# environment. This file is created mode 600 and belongs to you alone.",
+];
+/**
+ * The description + commented placeholder block for one credential. A
+ * description carrying newlines becomes one comment line per line, so no input
+ * can produce an uncommented line and quietly turn the file into a live
+ * assignment.
+ */
+function block(spec) {
+    const description = spec.description.split("\n").map((line) => `# ${line}`);
+    return ["", ...description, `# ${spec.key}=`];
+}
+/**
+ * The full content of a fresh secrets file: a header, then a commented
+ * placeholder per spec. Every line is a comment, so creating the file never
+ * changes what ghostrail resolves.
+ */
+export function renderFile(specs) {
+    const lines = [...HEADER];
+    for (const spec of specs)
+        lines.push(...block(spec));
+    return `${lines.join("\n")}\n`;
+}
+/**
+ * Append placeholder blocks for `specs` to existing content, preserving every
+ * byte of it up to its trailing newlines. Only the run of trailing newlines can
+ * change, which keeps repeated runs from stacking blank lines.
+ */
+export function appendPlaceholders(existing, specs) {
+    if (specs.length === 0)
+        return existing;
+    const base = existing.replace(/\n+$/, "");
+    const lines = ["# Added by ghostrail secrets-setup."];
+    for (const spec of specs)
+        lines.push(...block(spec));
+    const body = `${lines.join("\n")}\n`;
+    return base.trim().length === 0 ? body : `${base}\n\n${body}`;
+}
+/** The secrets file's content, or undefined when it does not exist. */
+export async function readSecretsFile(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Write the secrets file owner-only, creating its directory owner-only too. */
+export async function writeSecretsFile(path, content) {
+    await mkdir(dirname(path), { recursive: true, mode: SECRETS_DIR_MODE });
+    await writeFile(path, content, { encoding: "utf8", mode: SECRETS_FILE_MODE });
+}
+//# sourceMappingURL=setup.js.map

package/dist/secrets/setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../../src/secrets/setup.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ghostrail",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Open source software factory for coding agents. Config-driven loops, pluggable isolation backends, human merge gate.",
   "keywords": [
     "ai-agents",
@@ -24,7 +24,7 @@
   "bin": {
     "ghostrail": "dist/bin.js"
   },
-  "files": ["dist", "templates", "skill", "docker", "LICENSE", "NOTICE", "README.md"],
+  "files": ["dist", "templates", "skill", "docker", "scripts", "LICENSE", "NOTICE", "README.md"],
   "engines": {
     "node": ">=22"
   },

package/scripts/build-factory-image.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# Build the ghostrail factory toolchain image used by the container backend.
+# Usage: scripts/build-factory-image.sh [image-tag]   (default: ghostrail-factory:local)
+set -euo pipefail
+
+IMAGE="${1:-ghostrail-factory:local}"
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+docker build -f "$DIR/docker/factory.Dockerfile" -t "$IMAGE" "$DIR/docker"
+echo "built $IMAGE"

package/skill/ghostrail/SKILL.md

@@ -123,10 +123,19 @@ Diagnose a setup without changing anything. Check and report each, with the fix:
 - **Credentials** — report which of `LINEAR_API_KEY`, `GH_TOKEN`/`GITHUB_TOKEN`,
   and `ANTHROPIC_API_KEY` **or** `CLAUDE_CODE_OAUTH_TOKEN` are set. Report only
   set/unset, **never print a value**. Note that `ANTHROPIC_API_KEY` wins over the
-  OAuth token, so it must be unset to bill a Pro/Max subscription.
+  OAuth token, so it must be unset to bill a Pro/Max subscription. Remember they
+  can come from a file as well as the environment: `~/.config/ghostrail/secrets.env`
+  and a repo's `.ghostrail.env`, which beat an exported variable of the same name.
+  When something is missing, the fix to suggest is `ghostrail secrets-setup --write`,
+  which scaffolds that file and opens it in the user's editor. Never offer to fill
+  in a value yourself.
 - **GitHub** — `gh auth status` succeeds.
 - **Container backend**, if `[backend].kind = "container"` — the configured
-  `image` exists locally (`docker images`). If not, it must be built.
+  `image` exists locally (`docker images`). If not, the fix is
+  `ghostrail image build` (add `--tag` when the config names something other
+  than `ghostrail-factory:local`). No repo checkout is needed; the Dockerfile
+  ships in the package. A `local-worktree` factory needs no image at all, so do
+  not report a missing one as a problem.
 
 Finish with a short ordered list of what to fix first.