@genoventures-labs/deckhand 0.1.0

package/dist/lib/runs.js

@@ -0,0 +1,168 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { z } from "zod";
+import { listChecks, listRuns } from "./gh.js";
+import { formatStatus, gitAdd, gitCommit, gitPull, gitPush, gitStatus } from "./git.js";
+import { generateCommitMessage } from "./model.js";
+import { templatesRoot } from "./paths.js";
+import { workspaceRoot } from "./workspace.js";
+export const RUN_ACTIONS = ["status", "pull", "sync", "checks", "actions-list"];
+const cronField = z.string().regex(/^(\S+\s+){4}\S+$/, "cron must have 5 fields (min hour day month weekday)");
+const gatedRunSchema = z.object({
+    apiVersion: z.literal("deckhand/v1"),
+    kind: z.literal("GatedRun"),
+    metadata: z.object({
+        name: z.string().min(1),
+        description: z.string().optional(),
+    }),
+    spec: z.object({
+        schedule: z.object({
+            cron: cronField,
+            timezone: z.string().default("UTC"),
+        }),
+        action: z.enum(RUN_ACTIONS),
+        workspace: z.string().default("."),
+        gate: z
+            .object({
+            enabled: z.boolean().default(true),
+            environment: z.string().default("deckhand-gate"),
+            requireCleanTree: z.boolean().default(true),
+            requireChecks: z.boolean().default(false),
+        })
+            .default({
+            enabled: true,
+            environment: "deckhand-gate",
+            requireCleanTree: true,
+            requireChecks: false,
+        }),
+        sync: z
+            .object({
+            push: z.boolean().default(false),
+            message: z.string().optional(),
+        })
+            .optional(),
+    }),
+});
+export function userRunsDir(cwd) {
+    return join(workspaceRoot(cwd), ".deckhand", "runs");
+}
+export function packagedRunTemplatesDir() {
+    return join(templatesRoot(), "runs");
+}
+export function packagedWorkflowTemplatesDir() {
+    return join(templatesRoot(), "github-actions");
+}
+export function parseGatedRun(raw, source) {
+    const parsed = gatedRunSchema.safeParse(parseYaml(raw));
+    if (!parsed.success) {
+        throw new Error(`${source}: ${parsed.error.issues.map((issue) => issue.message).join("; ")}`);
+    }
+    return parsed.data;
+}
+export function loadRunFile(path) {
+    return { path, run: parseGatedRun(readFileSync(path, "utf8"), path) };
+}
+function yamlFiles(dir) {
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((name) => name.endsWith(".yaml") || name.endsWith(".yml"))
+        .map((name) => join(dir, name));
+}
+export function listTemplateRuns() {
+    return yamlFiles(packagedRunTemplatesDir()).map(loadRunFile);
+}
+export function listUserRuns(cwd) {
+    return yamlFiles(userRunsDir(cwd)).map(loadRunFile);
+}
+export function findRun(name, cwd) {
+    const fromUser = listUserRuns(cwd).find((entry) => entry.run.metadata.name === name);
+    if (fromUser)
+        return fromUser;
+    const fromTemplates = listTemplateRuns().find((entry) => entry.run.metadata.name === name);
+    if (fromTemplates)
+        return fromTemplates;
+    throw new Error(`No gated run named "${name}". Try: deckhand runs list`);
+}
+export function initRunTemplate(name, cwd) {
+    const template = listTemplateRuns().find((entry) => entry.run.metadata.name === name);
+    if (!template) {
+        const available = listTemplateRuns()
+            .map((entry) => entry.run.metadata.name)
+            .join(", ");
+        throw new Error(`Unknown template "${name}". Available: ${available}`);
+    }
+    const destDir = userRunsDir(cwd);
+    mkdirSync(destDir, { recursive: true });
+    const dest = join(destDir, basename(template.path));
+    writeFileSync(dest, readFileSync(template.path, "utf8"));
+    return dest;
+}
+export function installWorkflowTemplate(name, cwd) {
+    const source = join(packagedWorkflowTemplatesDir(), `${name}.yml`);
+    if (!existsSync(source)) {
+        const available = yamlFiles(packagedWorkflowTemplatesDir())
+            .map((path) => basename(path, ".yml"))
+            .join(", ");
+        throw new Error(`Unknown workflow template "${name}". Available: ${available}`);
+    }
+    const destDir = join(workspaceRoot(cwd), ".github", "workflows");
+    mkdirSync(destDir, { recursive: true });
+    const dest = join(destDir, `deckhand-${name}.yml`);
+    writeFileSync(dest, readFileSync(source, "utf8"));
+    return dest;
+}
+export async function applyRun(loaded, options) {
+    const { run } = loaded;
+    const cwd = options.cwd ?? run.spec.workspace;
+    const gate = run.spec.gate;
+    if (gate.enabled && !options.approve && process.env.DECKHAND_RUN_APPROVED !== "1") {
+        throw new Error(`Run "${run.metadata.name}" is gated by environment "${gate.environment}". Re-run with --approve after review, or set DECKHAND_RUN_APPROVED=1 on a trusted runner.`);
+    }
+    if (gate.requireCleanTree && run.spec.action !== "status" && run.spec.action !== "sync") {
+        const status = await gitStatus(cwd);
+        if (!status.clean) {
+            throw new Error(`Gate requires a clean tree:\n${formatStatus(status)}`);
+        }
+    }
+    if (gate.requireChecks) {
+        const checks = await listChecks(cwd);
+        if (/fail|pending|error/i.test(checks)) {
+            throw new Error(`Gate requires green PR checks:\n${checks}`);
+        }
+    }
+    const action = run.spec.action;
+    switch (action) {
+        case "status":
+            return formatStatus(await gitStatus(cwd));
+        case "pull":
+            return gitPull(cwd);
+        case "sync": {
+            const status = await gitStatus(cwd);
+            if (status.clean)
+                return "Working tree is clean. Nothing to sync.";
+            await gitAdd(["."], cwd);
+            const message = run.spec.sync?.message ?? (await generateCommitMessage(cwd));
+            const committed = await gitCommit(message, cwd);
+            if (run.spec.sync?.push) {
+                try {
+                    return `${committed}\n${await gitPush(cwd)}`;
+                }
+                catch {
+                    return `${committed}\n${await gitPush(cwd, true)}`;
+                }
+            }
+            return committed;
+        }
+        case "checks":
+            return listChecks(cwd);
+        case "actions-list":
+            return listRuns(cwd);
+        default: {
+            const exhaustive = action;
+            throw new Error(`Unhandled run action: ${String(exhaustive)}`);
+        }
+    }
+}
+//# sourceMappingURL=runs.js.map

package/dist/lib/runs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runs.js","sourceRoot":"","sources":["../../src/lib/runs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC1F,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAC1C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACxF,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,CAAU,CAAC;AAGzF,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,kBAAkB,EAAE,sDAAsD,CAAC,CAAC;AAE/G,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9B,UAAU,EAAE,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC;IACpC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;IAC3B,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC;QACjB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACvB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KACnC,CAAC;IACF,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;QACb,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC;YACjB,IAAI,EAAE,SAAS;YACf,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;SACpC,CAAC;QACF,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC;QAC3B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC;QAClC,IAAI,EAAE,CAAC;aACJ,MAAM,CAAC;YACN,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;YAClC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,eAAe,CAAC;YAChD,gBAAgB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;YAC3C,aAAa,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;SAC1C,CAAC;aACD,OAAO,CAAC;YACP,OAAO,EAAE,IAAI;YACb,WAAW,EAAE,eAAe;YAC5B,gBAAgB,EAAE,IAAI;YACtB,aAAa,EAAE,KAAK;SACrB,CAAC;QACJ,IAAI,EAAE,CAAC;aACJ,MAAM,CAAC;YACN,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;YAChC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;SAC/B,CAAC;aACD,QAAQ,EAAE;KACd,CAAC;CACH,CAAC,CAAC;AASH,MAAM,UAAU,WAAW,CAAC,GAAY;IACtC,OAAO,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,uBAAuB;IACrC,OAAO,IAAI,CAAC,aAAa,EAAE,EAAE,MAAM,CAAC,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,4BAA4B;IAC1C,OAAO,IAAI,CAAC,aAAa,EAAE,EAAE,gBAAgB,CAAC,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,GAAW,EAAE,MAAc;IACvD,MAAM,MAAM,GAAG,cAAc,CAAC,SAAS,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;IACxD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,GAAG,MAAM,KAAK,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAChG,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,aAAa,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,IAAI,CAAC,EAAE,CAAC;AACxE,CAAC;AAED,SAAS,SAAS,CAAC,GAAW;IAC5B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IAChC,OAAO,WAAW,CAAC,GAAG,CAAC;SACpB,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;SACjE,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,OAAO,SAAS,CAAC,uBAAuB,EAAE,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;AAC/D,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,OAAO,SAAS,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;AACtD,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,IAAY,EAAE,GAAY;IAChD,MAAM,QAAQ,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IACrF,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC9B,MAAM,aAAa,GAAG,gBAAgB,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IAC3F,IAAI,aAAa;QAAE,OAAO,aAAa,CAAC;IACxC,MAAM,IAAI,KAAK,CAAC,uBAAuB,IAAI,4BAA4B,CAAC,CAAC;AAC3E,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,GAAY;IACxD,MAAM,QAAQ,GAAG,gBAAgB,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IACtF,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,SAAS,GAAG,gBAAgB,EAAE;aACjC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC;aACvC,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,qBAAqB,IAAI,iBAAiB,SAAS,EAAE,CAAC,CAAC;IACzE,CAAC;IACD,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IACjC,SAAS,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACxC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;IACpD,aAAa,CAAC,IAAI,EAAE,YAAY,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IACzD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,IAAY,EAAE,GAAY;IAChE,MAAM,MAAM,GAAG,IAAI,CAAC,4BAA4B,EAAE,EAAE,GAAG,IAAI,MAAM,CAAC,CAAC;IACnE,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QACxB,MAAM,SAAS,GAAG,SAAS,CAAC,4BAA4B,EAAE,CAAC;aACxD,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;aACrC,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,8BAA8B,IAAI,iBAAiB,SAAS,EAAE,CAAC,CAAC;IAClF,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,SAAS,EAAE,WAAW,CAAC,CAAC;IACjE,SAAS,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACxC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,EAAE,YAAY,IAAI,MAAM,CAAC,CAAC;IACnD,aAAa,CAAC,IAAI,EAAE,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,MAAiB,EACjB,OAA4C;IAE5C,MAAM,EAAE,GAAG,EAAE,GAAG,MAAM,CAAC;IACvB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC;IAC9C,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC;IAE3B,IAAI,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,qBAAqB,KAAK,GAAG,EAAE,CAAC;QAClF,MAAM,IAAI,KAAK,CACb,QAAQ,GAAG,CAAC,QAAQ,CAAC,IAAI,8BAA8B,IAAI,CAAC,WAAW,4FAA4F,CACpK,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,CAAC,gBAAgB,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QACxF,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,GAAG,CAAC,CAAC;QACpC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,gCAAgC,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC1E,CAAC;IACH,CAAC;IAED,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;QACvB,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,GAAG,CAAC,CAAC;QACrC,IAAI,qBAAqB,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YACvC,MAAM,IAAI,KAAK,CAAC,mCAAmC,MAAM,EAAE,CAAC,CAAC;QAC/D,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAAc,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC;IAC1C,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,QAAQ;YACX,OAAO,YAAY,CAAC,MAAM,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;QAC5C,KAAK,MAAM;YACT,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC;QACtB,KAAK,MAAM,CAAC,CAAC,CAAC;YACZ,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,GAAG,CAAC,CAAC;YACpC,IAAI,MAAM,CAAC,KAAK;gBAAE,OAAO,yCAAyC,CAAC;YACnE,MAAM,MAAM,CAAC,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC;YACzB,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,IAAI,CAAC,MAAM,qBAAqB,CAAC,GAAG,CAAC,CAAC,CAAC;YAC7E,MAAM,SAAS,GAAG,MAAM,SAAS,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;YAChD,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC;gBACxB,IAAI,CAAC;oBACH,OAAO,GAAG,SAAS,KAAK,MAAM,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC/C,CAAC;gBAAC,MAAM,CAAC;oBACP,OAAO,GAAG,SAAS,KAAK,MAAM,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,CAAC;gBACrD,CAAC;YACH,CAAC;YACD,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,KAAK,QAAQ;YACX,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC;QACzB,KAAK,cAAc;YACjB,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC;QACvB,OAAO,CAAC,CAAC,CAAC;YACR,MAAM,UAAU,GAAU,MAAM,CAAC;YACjC,MAAM,IAAI,KAAK,CAAC,yBAAyB,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;QACjE,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/lib/watch.d.ts

@@ -0,0 +1,12 @@
+import { type GitStatus } from "./git.js";
+export type WatchHandle = {
+    close: () => void;
+};
+export type WatchEvent = {
+    ok: true;
+    status: GitStatus;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function watchWorkspace(cwd: string | undefined, onChange: (event: WatchEvent) => void): Promise<WatchHandle>;

package/dist/lib/watch.js

@@ -0,0 +1,38 @@
+import { watch as watchFiles } from "node:fs";
+import { resolve } from "node:path";
+import { loadConfig } from "./config.js";
+import { gitStatus } from "./git.js";
+import { workspaceRoot } from "./workspace.js";
+export async function watchWorkspace(cwd, onChange) {
+    const root = workspaceRoot(cwd);
+    const config = loadConfig(root);
+    const watchers = config.workspaces.map((relative) => {
+        const target = resolve(root, relative);
+        return watchFiles(target, { recursive: true }, debounce(800, async () => {
+            try {
+                onChange({ ok: true, status: await gitStatus(root) });
+            }
+            catch (error) {
+                onChange({ ok: false, error: error instanceof Error ? error.message : String(error) });
+            }
+        }));
+    });
+    onChange({ ok: true, status: await gitStatus(root) });
+    return {
+        close: () => {
+            for (const watcher of watchers)
+                watcher.close();
+        },
+    };
+}
+function debounce(ms, fn) {
+    let timer;
+    return () => {
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            void fn();
+        }, ms);
+    };
+}
+//# sourceMappingURL=watch.js.map

package/dist/lib/watch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.js","sourceRoot":"","sources":["../../src/lib/watch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,UAAU,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,SAAS,EAAkB,MAAM,UAAU,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAQ/C,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,GAAuB,EACvB,QAAqC;IAErC,MAAM,IAAI,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;IAChC,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAChC,MAAM,QAAQ,GAAG,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE;QAClD,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACvC,OAAO,UAAU,CACf,MAAM,EACN,EAAE,SAAS,EAAE,IAAI,EAAE,EACnB,QAAQ,CAAC,GAAG,EAAE,KAAK,IAAI,EAAE;YACvB,IAAI,CAAC;gBACH,QAAQ,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACxD,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,QAAQ,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YACzF,CAAC;QACH,CAAC,CAAC,CACH,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEtD,OAAO;QACL,KAAK,EAAE,GAAG,EAAE;YACV,KAAK,MAAM,OAAO,IAAI,QAAQ;gBAAE,OAAO,CAAC,KAAK,EAAE,CAAC;QAClD,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,QAAQ,CAAC,EAAU,EAAE,EAA8B;IAC1D,IAAI,KAAgD,CAAC;IACrD,OAAO,GAAG,EAAE;QACV,IAAI,KAAK;YAAE,YAAY,CAAC,KAAK,CAAC,CAAC;QAC/B,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YACtB,KAAK,EAAE,EAAE,CAAC;QACZ,CAAC,EAAE,EAAE,CAAC,CAAC;IACT,CAAC,CAAC;AACJ,CAAC"}

package/dist/lib/workspace.d.ts

@@ -0,0 +1 @@
+export declare function workspaceRoot(explicit?: string): string;

package/dist/lib/workspace.js

@@ -0,0 +1,5 @@
+import { resolve } from "node:path";
+export function workspaceRoot(explicit) {
+    return resolve(explicit ?? process.env.DECKHAND_CWD ?? process.cwd());
+}
+//# sourceMappingURL=workspace.js.map

package/dist/lib/workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../../src/lib/workspace.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,MAAM,UAAU,aAAa,CAAC,QAAiB;IAC7C,OAAO,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;AACxE,CAAC"}

package/dist/ui/format.d.ts

@@ -0,0 +1,16 @@
+import type { DoctorCheck } from "../lib/doctor.js";
+import type { GitStatus } from "../lib/git.js";
+import type { LoadedRun } from "../lib/runs.js";
+export declare function banner(): string;
+export declare function section(title: string): string;
+export declare function notice(kind: "ok" | "fail" | "warn" | "info", message: string): string;
+export declare function print(text: string): void;
+export declare function printError(message: string): void;
+export declare function doctorTable(checks: DoctorCheck[]): string;
+export declare function statusTables(status: GitStatus): string;
+export declare function runsTables(templates: LoadedRun[], local: LoadedRun[]): string;
+export declare function kvTable(title: string, entries: Record<string, string>): string;
+export declare function commandTable(groups: {
+    title: string;
+    rows: [string, string][];
+}[]): string;

package/dist/ui/format.js

@@ -0,0 +1,82 @@
+import { renderTable } from "./table.js";
+import { theme, VERSION } from "./theme.js";
+export function banner() {
+    const rule = theme.muted("─".repeat(Math.min(56, process.stdout.columns ?? 56)));
+    return [
+        theme.brand("Deckhand") + theme.muted(`  v${VERSION}`),
+        theme.muted("Git, GitHub, and gated runs — via Eve and AI Gateway"),
+        rule,
+    ].join("\n");
+}
+export function section(title) {
+    return theme.heading(title);
+}
+export function notice(kind, message) {
+    const tag = kind === "ok"
+        ? theme.ok("ok")
+        : kind === "fail"
+            ? theme.fail("fail")
+            : kind === "warn"
+                ? theme.warn("warn")
+                : theme.info("info");
+    return `${tag}  ${message}`;
+}
+export function print(text) {
+    console.log(text);
+}
+export function printError(message) {
+    console.error(notice("fail", message));
+}
+export function doctorTable(checks) {
+    const rows = checks.map((check) => [
+        check.name,
+        check.ok ? theme.ok("pass") : theme.fail("fail"),
+        check.detail,
+    ]);
+    return [section("Doctor"), renderTable(["Check", "Status", "Detail"], rows)].join("\n");
+}
+export function statusTables(status) {
+    const tracking = status.ahead || status.behind ? `ahead ${status.ahead} / behind ${status.behind}` : "in sync";
+    const meta = renderTable(["Field", "Value"], [
+        ["Repo", status.cwd],
+        ["Branch", `${status.branch}${status.detached ? " (detached)" : ""}`],
+        ["Tracking", tracking],
+        ["Tree", status.clean ? theme.ok("clean") : theme.warn(`${status.changes.length} changes`)],
+    ]);
+    if (status.clean) {
+        return [section("Status"), meta, notice("ok", "Working tree is clean.")].join("\n");
+    }
+    const changes = renderTable(["Kind", "Index", "Worktree", "Path"], status.changes.map((change) => [
+        change.kind,
+        change.index.trim() ? change.index : "·",
+        change.worktree.trim() ? change.worktree : "·",
+        change.path,
+    ]));
+    return [section("Status"), meta, "", section("Changes"), changes].join("\n");
+}
+export function runsTables(templates, local) {
+    const toRows = (entries, source) => entries.map((entry) => [
+        entry.run.metadata.name,
+        entry.run.spec.schedule.cron,
+        entry.run.spec.schedule.timezone,
+        entry.run.spec.action,
+        entry.run.spec.gate.enabled ? theme.warn(entry.run.spec.gate.environment) : theme.ok("ungated"),
+        source,
+        entry.run.metadata.description ?? "",
+    ]);
+    const headers = ["Name", "Cron", "Timezone", "Action", "Gate", "Source", "Description"];
+    const rows = [...toRows(templates, "template"), ...toRows(local, "local")];
+    return [section("Gated runs"), renderTable(headers, rows)].join("\n");
+}
+export function kvTable(title, entries) {
+    return [
+        section(title),
+        renderTable(["Key", "Value"], Object.entries(entries).map(([key, value]) => [key, value])),
+    ].join("\n");
+}
+export function commandTable(groups) {
+    return groups
+        .map((group) => [section(group.title), renderTable(["Command", "What it does"], group.rows)].join("\n"))
+        .join("\n\n");
+}
+//# sourceMappingURL=format.js.map

package/dist/ui/format.js.map

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

package/dist/ui/help.d.ts

@@ -0,0 +1,7 @@
+import type { Command } from "commander";
+export declare const HELP_TOPICS: readonly ["getting-started", "git", "github", "runs", "gateway", "examples"];
+export type HelpTopic = (typeof HELP_TOPICS)[number];
+export declare function printRootHelp(program: Command): void;
+export declare function printTopicIndex(): void;
+export declare function printTopic(topic: HelpTopic): void;
+export declare function showHelpTopicOrCommand(program: Command, topic?: string): void;

package/dist/ui/help.js

@@ -0,0 +1,197 @@
+import { banner, commandTable, print, section } from "./format.js";
+import { renderTable } from "./table.js";
+import { theme } from "./theme.js";
+export const HELP_TOPICS = [
+    "getting-started",
+    "git",
+    "github",
+    "runs",
+    "gateway",
+    "examples",
+];
+function isHelpTopic(value) {
+    return HELP_TOPICS.includes(value);
+}
+export function printRootHelp(program) {
+    print([
+        banner(),
+        "",
+        theme.muted("Usage"),
+        "  deckhand <command> [options]",
+        "  deckhand help [topic|command]",
+        "",
+        commandTable([
+            {
+                title: "Workspace",
+                rows: [
+                    ["doctor", "Check git, gh, AI Gateway, and Node"],
+                    ["status", "Repo, branch, and change table"],
+                    ["watch", "Live status as files change"],
+                    ["config", "Resolved Deckhand settings"],
+                ],
+            },
+            {
+                title: "Git",
+                rows: [
+                    ["sync", "Stage, commit (Gateway message), push"],
+                    ["pull", "Fast-forward pull"],
+                    ["branch <name>", "Create or switch a branch"],
+                    ["conflicts", "Conflict list plus model guidance"],
+                ],
+            },
+            {
+                title: "GitHub",
+                rows: [
+                    ["pr create", "Open a pull request"],
+                    ["issue create", "Open an issue"],
+                    ["repo create", "Create a repository"],
+                    ["project create", "Create a GitHub Project"],
+                    ["checks", "PR status checks"],
+                    ["actions list|watch|run", "GitHub Actions"],
+                ],
+            },
+            {
+                title: "Automation",
+                rows: [
+                    ["runs", "Gated YAML schedules and templates"],
+                    ["agent", "Start the Eve terminal session"],
+                ],
+            },
+        ]),
+        "",
+        section("Help"),
+        renderTable(["Command", "Opens"], [
+            ["deckhand help", "This overview"],
+            ["deckhand help topics", "All help topics"],
+            ["deckhand help runs", "Gated-run guide"],
+            ["deckhand <command> --help", "Flags for one command"],
+        ]),
+        "",
+        theme.muted("Global flags: -h, --help    -V, --version    -C, --cwd <path> on most commands"),
+    ].join("\n"));
+    void program;
+}
+export function printTopicIndex() {
+    print([
+        banner(),
+        "",
+        section("Help topics"),
+        renderTable(["Topic", "Covers"], [
+            ["getting-started", "Install, auth, first commands"],
+            ["git", "status, watch, sync, pull, conflicts"],
+            ["github", "pr, issue, repo, project, checks, actions"],
+            ["runs", "YAML gated runs and GitHub Environments"],
+            ["gateway", "AI Gateway keys and models"],
+            ["examples", "Copy-paste command recipes"],
+        ]),
+        "",
+        theme.muted("deckhand help <topic>"),
+    ].join("\n"));
+}
+export function printTopic(topic) {
+    const body = topicBody(topic);
+    print([banner(), "", body].join("\n"));
+}
+function topicBody(topic) {
+    switch (topic) {
+        case "getting-started":
+            return [
+                section("Getting started"),
+                "1. npm install && npm run build",
+                "2. gh auth login",
+                "3. Copy .env.example to .env.local and set AI_GATEWAY_API_KEY",
+                "4. deckhand doctor",
+                "5. deckhand status",
+                "",
+                theme.muted("Eve agent (Node 24+): deckhand agent"),
+            ].join("\n");
+        case "git":
+            return [
+                section("Git"),
+                "deckhand status              Change table for the current repo",
+                "deckhand watch               Reprint status on filesystem events",
+                "deckhand pull                git pull --ff-only",
+                "deckhand sync                add + Gateway commit message + push",
+                "deckhand sync --no-push      commit only",
+                "deckhand sync -m \"msg\"       skip the model",
+                "deckhand branch topic/fix    create or switch",
+                "deckhand conflicts           list + resolution notes",
+                "",
+                theme.muted("Never force-pushes. Pulls are fast-forward only."),
+            ].join("\n");
+        case "github":
+            return [
+                section("GitHub"),
+                "Requires gh on PATH (deckhand doctor).",
+                "",
+                "deckhand pr create -t \"Title\"",
+                "deckhand issue create -t \"Title\"",
+                "deckhand repo create my-repo --private",
+                "deckhand project create -t \"Board\" -o my-org",
+                "deckhand checks",
+                "deckhand actions list",
+                "deckhand actions watch [runId]",
+                "deckhand actions run ci.yml --ref main",
+            ].join("\n");
+        case "runs":
+            return [
+                section("Gated runs"),
+                "YAML under templates/runs and .deckhand/runs.",
+                "GitHub Environment deckhand-gate holds execute jobs for review.",
+                "",
+                "deckhand runs list",
+                "deckhand runs init morning-pull",
+                "deckhand runs install-workflow morning-pull",
+                "deckhand runs apply morning-pull --approve",
+                "",
+                "Gated apply without --approve exits with an error on purpose.",
+                "GitHub cron is UTC; YAML timezone documents local intent.",
+            ].join("\n");
+        case "gateway":
+            return [
+                section("AI Gateway"),
+                "Set AI_GATEWAY_API_KEY, or vercel link && vercel env pull .env.local",
+                "Default model: openai/gpt-5.6-luna-fast",
+                "Override with DECKHAND_MODEL or deckhand.json { \"model\": \"provider/model\" }",
+                "",
+                "deckhand doctor     shows whether credentials resolved",
+                "deckhand config     prints the effective model and workspaces",
+            ].join("\n");
+        case "examples":
+            return [
+                section("Examples"),
+                "deckhand doctor",
+                "deckhand status -C ../other-repo",
+                "deckhand sync --no-push",
+                "deckhand pr create -t \"Tighten pull gates\" --draft",
+                "deckhand runs list",
+                "deckhand help git",
+            ].join("\n");
+        default: {
+            const exhaustive = topic;
+            return String(exhaustive);
+        }
+    }
+}
+export function showHelpTopicOrCommand(program, topic) {
+    if (!topic || topic === "help") {
+        printRootHelp(program);
+        return;
+    }
+    if (topic === "topics") {
+        printTopicIndex();
+        return;
+    }
+    if (isHelpTopic(topic)) {
+        printTopic(topic);
+        return;
+    }
+    const command = program.commands.find((entry) => entry.name() === topic || entry.aliases().includes(topic));
+    if (command) {
+        command.outputHelp();
+        return;
+    }
+    print(`${theme.fail("Unknown help topic:")} ${topic}`);
+    printTopicIndex();
+}
+//# sourceMappingURL=help.js.map

package/dist/ui/help.js.map

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

package/dist/ui/table.d.ts

@@ -0,0 +1,4 @@
+export declare function visibleWidth(text: string): number;
+export declare function padVisible(text: string, width: number): string;
+export declare function truncate(text: string, max: number): string;
+export declare function renderTable(headers: string[], rows: string[][]): string;

package/dist/ui/table.js

@@ -0,0 +1,39 @@
+export function visibleWidth(text) {
+    return text.replace(/\u001b\[[0-9;]*m/g, "").length;
+}
+export function padVisible(text, width) {
+    const pad = Math.max(0, width - visibleWidth(text));
+    return `${text}${" ".repeat(pad)}`;
+}
+export function truncate(text, max) {
+    if (visibleWidth(text) <= max)
+        return text;
+    if (max <= 1)
+        return "…";
+    return `${text.replace(/\u001b\[[0-9;]*m/g, "").slice(0, Math.max(0, max - 1))}…`;
+}
+export function renderTable(headers, rows) {
+    if (rows.length === 0) {
+        return `${headers.join("  ")}\n  (none)`;
+    }
+    const colCount = headers.length;
+    const budget = Math.max(60, (process.stdout.columns ?? 100) - 4);
+    const widths = headers.map((header, index) => {
+        const longest = Math.max(header.length, ...rows.map((row) => visibleWidth(row[index] ?? "")));
+        return Math.min(longest, index === colCount - 1 ? 80 : 36);
+    });
+    const total = widths.reduce((sum, width) => sum + width, 0) + (colCount - 1) * 3 + 4;
+    if (total > budget && widths.length > 0) {
+        const overflow = total - budget;
+        widths[widths.length - 1] = Math.max(16, widths[widths.length - 1] - overflow);
+    }
+    const top = `┌${widths.map((width) => "─".repeat(width + 2)).join("┬")}┐`;
+    const mid = `├${widths.map((width) => "─".repeat(width + 2)).join("┼")}┤`;
+    const bottom = `└${widths.map((width) => "─".repeat(width + 2)).join("┴")}┘`;
+    const formatRow = (cells) => {
+        const padded = cells.map((cell, index) => padVisible(truncate(cell ?? "", widths[index] ?? 0), widths[index] ?? 0));
+        return `│ ${padded.join(" │ ")} │`;
+    };
+    return [top, formatRow(headers), mid, ...rows.map(formatRow), bottom].join("\n");
+}
+//# sourceMappingURL=table.js.map

package/dist/ui/table.js.map

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

package/dist/ui/theme.d.ts

@@ -0,0 +1,14 @@
+import { styleText } from "node:util";
+export declare function paint(style: Parameters<typeof styleText>[0], text: string): string;
+export declare const theme: {
+    brand: (text: string) => string;
+    muted: (text: string) => string;
+    heading: (text: string) => string;
+    ok: (text: string) => string;
+    fail: (text: string) => string;
+    warn: (text: string) => string;
+    info: (text: string) => string;
+    label: (text: string) => string;
+    path: (text: string) => string;
+};
+export declare const VERSION = "0.1.0";