@boardwalk-labs/cli 0.1.0

package/dist/commands/init.js

@@ -0,0 +1,171 @@
+// `boardwalk init [dir]` — scaffold a new workflow project.
+//
+// Templates come from the examples registry: `--template <name>` fetches
+// `registry.json` and the template's files from the templates base URL
+// ($BOARDWALK_TEMPLATES_URL to point at a fork/mirror). The default `hello` template is
+// BUILT IN — `init` works offline and with zero configuration.
+//
+// Never overwrites: every target path is checked before anything is written.
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { CliError } from "../errors.js";
+/** Where templates live: the examples repo, raw. Overridable for forks/mirrors. */
+const DEFAULT_TEMPLATES_URL = "https://raw.githubusercontent.com/boardwalk-labs/examples/main";
+// ── The built-in `hello` template (offline floor) ───────────────────────────────────────
+const HELLO_PROGRAM = `import { input, output, type WorkflowMeta } from "@boardwalk-labs/workflow";
+
+export const meta = {
+  name: "{{name}}",
+  description: "A starting point — run it locally with \`boardwalk dev\`.",
+  triggers: [{ kind: "manual" }],
+} satisfies WorkflowMeta;
+
+// A workflow is a script: it runs top to bottom, and top-level await just works.
+const who = typeof input === "string" && input.length > 0 ? input : "world";
+
+// Next step: give it a brain. agent() runs a full agent loop and resolves to its answer:
+//   const greeting = await agent(\`Write a one-line greeting for \${who}.\`);
+// (agent() needs an engine — \`boardwalk run\` today, the local engine soon.)
+
+output(\`Hello, \${who}!\`);
+`;
+const HELLO_PACKAGE_JSON = `{
+  "name": "{{name}}",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@boardwalk-labs/workflow": "^0.1.0"
+  }
+}
+`;
+const HELLO_ENV_EXAMPLE = `# Secrets for local runs — \`boardwalk dev\` resolves meta.secrets from .env.
+# Copy to .env (gitignored) and fill in real values.
+# MY_API_KEY=…
+`;
+const HELLO_GITIGNORE = `node_modules/
+.env
+.boardwalk/
+.bw-runs/
+`;
+const BUILTIN_TEMPLATES = {
+    hello: {
+        "index.ts": HELLO_PROGRAM,
+        "package.json": HELLO_PACKAGE_JSON,
+        ".env.example": HELLO_ENV_EXAMPLE,
+        ".gitignore": HELLO_GITIGNORE,
+    },
+};
+export async function runInit(opts, deps = {}) {
+    const log = deps.log ??
+        ((line) => {
+            console.log(line);
+        });
+    const builtin = BUILTIN_TEMPLATES[opts.template];
+    if (builtin !== undefined) {
+        const dir = resolve(opts.dir);
+        const name = workflowNameFor(dir);
+        const files = Object.fromEntries(Object.entries(builtin).map(([rel, body]) => [rel, body.replaceAll("{{name}}", name)]));
+        scaffold(dir, files);
+        finish(log, opts, name, opts.template, []);
+        return;
+    }
+    // Remote template: registry lookup, then fetch each listed file.
+    const env = deps.env ?? process.env;
+    const baseUrl = (env.BOARDWALK_TEMPLATES_URL ?? DEFAULT_TEMPLATES_URL).replace(/\/+$/, "");
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const registry = await fetchRegistry(baseUrl, fetchImpl);
+    const template = registry.find((t) => t.name === opts.template);
+    if (template === undefined) {
+        const available = [...Object.keys(BUILTIN_TEMPLATES), ...registry.map((t) => t.name)];
+        throw new CliError(`Unknown template "${opts.template}".`, `Available templates: ${available.join(", ")}.`);
+    }
+    const files = {};
+    for (const rel of template.files) {
+        if (rel.startsWith("/") || rel.split("/").some((s) => s === ".." || s === "")) {
+            throw new CliError(`The registry lists an unsafe file path: ${rel}`);
+        }
+        files[rel] = await fetchText(`${baseUrl}/templates/${template.name}/${rel}`, fetchImpl, `template file ${rel}`);
+    }
+    scaffold(resolve(opts.dir), files);
+    finish(log, opts, template.name, template.name, template.secrets);
+}
+// ── Helpers ─────────────────────────────────────────────────────────────────────────────
+/** All-or-nothing write: refuse if ANY target exists, then write every file. */
+function scaffold(dir, files) {
+    mkdirSync(dir, { recursive: true });
+    for (const rel of Object.keys(files)) {
+        if (existsSync(join(dir, rel))) {
+            throw new CliError(`${rel} already exists in ${dir}.`, "boardwalk init only scaffolds into paths it won't overwrite — pick an empty directory.");
+        }
+    }
+    for (const [rel, contents] of Object.entries(files)) {
+        const target = join(dir, rel);
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, contents);
+    }
+}
+function finish(log, opts, name, template, secrets) {
+    log(`✓ scaffolded "${name}" (template: ${template})`);
+    log("");
+    log("next:");
+    log(`  cd ${opts.dir === "." ? "." : opts.dir} && npm install`);
+    if (secrets.length > 0) {
+        log(`  cp .env.example .env   # fill in: ${secrets.join(", ")}`);
+    }
+    log("  boardwalk dev .");
+}
+async function fetchRegistry(baseUrl, fetchImpl) {
+    const raw = await fetchText(`${baseUrl}/registry.json`, fetchImpl, "template registry");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new CliError("The template registry is not valid JSON.", registryHint(baseUrl));
+    }
+    const templates = typeof parsed === "object" && parsed !== null
+        ? parsed.templates
+        : undefined;
+    if (!Array.isArray(templates) || !templates.every(isRegistryTemplate)) {
+        throw new CliError("The template registry has an unexpected shape.", registryHint(baseUrl));
+    }
+    return templates;
+}
+async function fetchText(url, fetchImpl, what) {
+    let res;
+    try {
+        res = await fetchImpl(url, { signal: AbortSignal.timeout(20_000) });
+    }
+    catch (err) {
+        throw new CliError(`Could not fetch the ${what} (${url}).`, err instanceof Error ? err.message : undefined);
+    }
+    if (!res.ok) {
+        throw new CliError(`Fetching the ${what} failed (${String(res.status)}) at ${url}.`);
+    }
+    return res.text();
+}
+function registryHint(baseUrl) {
+    return `Registry base: ${baseUrl} (override with BOARDWALK_TEMPLATES_URL).`;
+}
+function isRegistryTemplate(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return (typeof v.name === "string" &&
+        typeof v.description === "string" &&
+        Array.isArray(v.secrets) &&
+        v.secrets.every((s) => typeof s === "string") &&
+        Array.isArray(v.files) &&
+        v.files.every((f) => typeof f === "string") &&
+        v.files.length > 0);
+}
+/** Derive a manifest-legal workflow name from the target directory's basename. */
+export function workflowNameFor(absDir) {
+    const base = basename(absDir)
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 100);
+    return base.length > 0 ? base : "my-workflow";
+}
+//# sourceMappingURL=init.js.map

package/dist/commands/init.js.map

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

package/dist/commands/run.d.ts

@@ -0,0 +1,32 @@
+import type { CliConfig } from "../config.js";
+import { type RunSummary } from "../client.js";
+import type { FetchLike } from "../auth/pkce.js";
+export declare function isTerminalStatus(status: string): boolean;
+/** Minimal client surface `pollToTerminal` needs — `BoardwalkClient` satisfies it. */
+export interface RunReader {
+    getRun(runId: string): Promise<RunSummary>;
+}
+export interface PollOptions {
+    sleep?: (ms: number) => Promise<void>;
+    intervalMs?: number;
+    timeoutMs?: number;
+    onStatus?: (status: string) => void;
+    now?: () => number;
+}
+/** Poll a run until it reaches a terminal state (completed/failed/cancelled), or time out. */
+export declare function pollToTerminal(client: RunReader, runId: string, opts?: PollOptions): Promise<RunSummary>;
+export interface RunOptions {
+    file: string;
+    org?: string | undefined;
+    input?: string | undefined;
+    token?: string | undefined;
+    noWait?: boolean;
+}
+export interface RunDeps {
+    config: CliConfig;
+    fetchImpl?: FetchLike;
+    log?: (line: string) => void;
+}
+export declare function runRun(opts: RunOptions, deps: RunDeps): Promise<void>;
+/** Parse `--input '<json>'` to a value; undefined when absent. Throws on malformed JSON. */
+export declare function parseInput(raw: string | undefined): unknown;

package/dist/commands/run.js

@@ -0,0 +1,105 @@
+// `boardwalk run <file|dir> --org <slug>` — actually run a workflow, for real.
+//
+// Runs on the PLATFORM (where the real worker + real inference live — no mocks): it deploys the
+// current source (via the project link), triggers a run, and polls it to a terminal state. The
+// run's output payload isn't exposed over REST (dashboard-only), so we report the final
+// status/outcome + the run id and point at the dashboard for full output + logs.
+import { CliError } from "../errors.js";
+import { CredentialStore } from "../credentials.js";
+import { resolveToken } from "../auth/resolve.js";
+import { BoardwalkClient } from "../client.js";
+import { deployWithLink, loadProgram } from "../deployment.js";
+const TERMINAL_STATUSES = new Set(["completed", "failed", "cancelled"]);
+const DEFAULT_POLL_INTERVAL_MS = 2_000;
+const DEFAULT_TIMEOUT_MS = 15 * 60_000;
+export function isTerminalStatus(status) {
+    return TERMINAL_STATUSES.has(status);
+}
+/** Poll a run until it reaches a terminal state (completed/failed/cancelled), or time out. */
+export async function pollToTerminal(client, runId, opts = {}) {
+    const sleep = opts.sleep ??
+        ((ms) => new Promise((resolve) => {
+            setTimeout(() => {
+                resolve();
+            }, ms);
+        }));
+    const intervalMs = opts.intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const now = opts.now ?? (() => Date.now());
+    const start = now();
+    let lastStatus = "";
+    for (;;) {
+        const run = await client.getRun(runId);
+        if (run.status !== lastStatus) {
+            opts.onStatus?.(run.status);
+            lastStatus = run.status;
+        }
+        if (isTerminalStatus(run.status))
+            return run;
+        if (now() - start > timeoutMs) {
+            throw new CliError(`Run ${runId} did not finish within ${String(Math.round(timeoutMs / 1000))}s (still ${run.status}).`, "It may still be running — check the run in the dashboard.");
+        }
+        await sleep(intervalMs);
+    }
+}
+export async function runRun(opts, deps) {
+    const log = deps.log ??
+        ((line) => {
+            console.log(line);
+        });
+    const prog = await loadProgram(opts.file);
+    const assets = prog.artifact.assetPaths.length;
+    log(`  built ${prog.entry} (${String(prog.artifact.size)} bytes${assets > 0 ? `, ${String(assets)} asset${assets === 1 ? "" : "s"}` : ""})`);
+    const store = CredentialStore.atConfigDir(deps.config.configDir);
+    const token = await resolveToken({
+        config: deps.config,
+        store,
+        tokenFlag: opts.token,
+        ...(deps.fetchImpl !== undefined ? { fetchImpl: deps.fetchImpl } : {}),
+    });
+    const client = new BoardwalkClient({
+        baseUrl: deps.config.apiBaseUrl,
+        token,
+        ...(deps.fetchImpl !== undefined ? { fetchImpl: deps.fetchImpl } : {}),
+    });
+    const dep = await deployWithLink(client, { orgSlug: opts.org, target: opts.file, prog });
+    if (dep.gitignoreUpdated)
+        log("  linked → .boardwalk/project.json (added .boardwalk/ to .gitignore)");
+    log(`✓ ${dep.outcome} "${prog.name}" version ${String(dep.versionNumber)}`);
+    const input = parseInput(opts.input);
+    const run = await client.triggerRun(dep.orgSlug, dep.workflowId, input);
+    log(`▶ run ${run.id} triggered (${run.status})`);
+    if (opts.noWait === true) {
+        log("  --no-wait: not polling. Check the run in the dashboard.");
+        return;
+    }
+    log(`  (cancel anytime: boardwalk cancel ${run.id})`);
+    const terminal = await pollToTerminal(client, run.id, {
+        onStatus: (status) => {
+            log(`  status → ${status}`);
+        },
+    });
+    printOutcome(log, terminal);
+    if (terminal.status !== "completed") {
+        throw new CliError(`Run ${terminal.status}.`, "See the run in the dashboard for logs + output.");
+    }
+}
+/** Parse `--input '<json>'` to a value; undefined when absent. Throws on malformed JSON. */
+export function parseInput(raw) {
+    if (raw === undefined)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new CliError("--input is not valid JSON.");
+    }
+}
+function printOutcome(log, run) {
+    log("──────── run result ────────");
+    log(`run:     ${run.id}`);
+    log(`status:  ${run.status}`);
+    log(`outcome: ${run.outcomeStatus ?? "(none)"}`);
+    log("output:  view the full output + logs in the dashboard");
+}
+//# sourceMappingURL=run.js.map

package/dist/commands/run.js.map

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

package/dist/commands/session.d.ts

@@ -0,0 +1,13 @@
+import type { CliConfig } from "../config.js";
+export interface SessionDeps {
+    config: CliConfig;
+    log?: (line: string) => void;
+}
+export interface LoginOptions {
+    /** Persist this API key (`bwk_…`) instead of running the browser PKCE flow. */
+    token?: string | undefined;
+}
+export declare function runLogin(deps: SessionDeps, opts?: LoginOptions): Promise<void>;
+export declare function runLogout(deps: SessionDeps): void;
+/** Report whether a stored session exists. (Identity claims live in the JWT; v0 keeps this minimal.) */
+export declare function runWhoami(deps: SessionDeps): void;

package/dist/commands/session.js

@@ -0,0 +1,58 @@
+// `boardwalk login` / `logout` / `whoami` — session lifecycle.
+import { CliError } from "../errors.js";
+import { CredentialStore } from "../credentials.js";
+import { performLogin } from "../auth/login.js";
+export async function runLogin(deps, opts = {}) {
+    const log = deps.log ??
+        ((line) => {
+            console.log(line);
+        });
+    const store = CredentialStore.atConfigDir(deps.config.configDir);
+    // First-class API-key auth: `boardwalk login --token <key>` stores the key like a
+    // non-expiring, non-refreshable session, so every command resolves it without re-setting
+    // BOARDWALK_API_KEY. (Not validated here — the first request rejects a bad key.) The two
+    // non-interactive paths (env BOARDWALK_API_KEY, --token per command) still work too.
+    const token = opts.token?.trim();
+    if (token !== undefined && token.length > 0) {
+        store.putSession({
+            accessToken: token,
+            refreshToken: null,
+            expiresAt: null,
+            clientId: null,
+            tokenEndpoint: null,
+            scope: "api-key",
+        });
+        log("✓ Stored API key.");
+        return;
+    }
+    const session = await performLogin({ config: deps.config, store, log });
+    const expiry = session.expiresAt !== null ? ` (expires ${new Date(session.expiresAt).toISOString()})` : "";
+    log(`✓ Logged in.${expiry}`);
+}
+export function runLogout(deps) {
+    const log = deps.log ??
+        ((line) => {
+            console.log(line);
+        });
+    const store = CredentialStore.atConfigDir(deps.config.configDir);
+    store.clear();
+    log("✓ Logged out — local credentials removed.");
+}
+/** Report whether a stored session exists. (Identity claims live in the JWT; v0 keeps this minimal.) */
+export function runWhoami(deps) {
+    const log = deps.log ??
+        ((line) => {
+            console.log(line);
+        });
+    const store = CredentialStore.atConfigDir(deps.config.configDir);
+    const session = store.getSession();
+    if (session === null) {
+        throw new CliError("Not logged in.", "Run `boardwalk login` (or `boardwalk login --token <key>`).");
+    }
+    // A stored API key has no token endpoint / refresh token; an OAuth session does.
+    const method = session.tokenEndpoint === null ? "API key" : "OAuth session";
+    const scope = session.scope ?? "(none)";
+    const expiry = session.expiresAt !== null ? new Date(session.expiresAt).toISOString() : "never";
+    log(`Logged in via ${method}. scope=${scope} expires=${expiry}`);
+}
+//# sourceMappingURL=session.js.map

package/dist/commands/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/commands/session.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAE/D,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAExC,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAYhD,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAiB,EAAE,OAAqB,EAAE;IACvE,MAAM,GAAG,GACP,IAAI,CAAC,GAAG;QACR,CAAC,CAAC,IAAY,EAAQ,EAAE;YACtB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC,CAAC,CAAC;IACL,MAAM,KAAK,GAAG,eAAe,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAEjE,kFAAkF;IAClF,yFAAyF;IACzF,yFAAyF;IACzF,qFAAqF;IACrF,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC;IACjC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5C,KAAK,CAAC,UAAU,CAAC;YACf,WAAW,EAAE,KAAK;YAClB,YAAY,EAAE,IAAI;YAClB,SAAS,EAAE,IAAI;YACf,QAAQ,EAAE,IAAI;YACd,aAAa,EAAE,IAAI;YACnB,KAAK,EAAE,SAAS;SACjB,CAAC,CAAC;QACH,GAAG,CAAC,mBAAmB,CAAC,CAAC;QACzB,OAAO;IACT,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;IACxE,MAAM,MAAM,GACV,OAAO,CAAC,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,aAAa,IAAI,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9F,GAAG,CAAC,eAAe,MAAM,EAAE,CAAC,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,IAAiB;IACzC,MAAM,GAAG,GACP,IAAI,CAAC,GAAG;QACR,CAAC,CAAC,IAAY,EAAQ,EAAE;YACtB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC,CAAC,CAAC;IACL,MAAM,KAAK,GAAG,eAAe,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACjE,KAAK,CAAC,KAAK,EAAE,CAAC;IACd,GAAG,CAAC,2CAA2C,CAAC,CAAC;AACnD,CAAC;AAED,wGAAwG;AACxG,MAAM,UAAU,SAAS,CAAC,IAAiB;IACzC,MAAM,GAAG,GACP,IAAI,CAAC,GAAG;QACR,CAAC,CAAC,IAAY,EAAQ,EAAE;YACtB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC,CAAC,CAAC;IACL,MAAM,KAAK,GAAG,eAAe,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACjE,MAAM,OAAO,GAAG,KAAK,CAAC,UAAU,EAAE,CAAC;IACnC,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACrB,MAAM,IAAI,QAAQ,CAChB,gBAAgB,EAChB,6DAA6D,CAC9D,CAAC;IACJ,CAAC;IACD,iFAAiF;IACjF,MAAM,MAAM,GAAG,OAAO,CAAC,aAAa,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC;IAC5E,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,QAAQ,CAAC;IACxC,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;IAChG,GAAG,CAAC,iBAAiB,MAAM,WAAW,KAAK,YAAY,MAAM,EAAE,CAAC,CAAC;AACnE,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,14 @@
+export interface CliConfig {
+    /** REST API base, e.g. https://api.boardwalk.sh (no trailing slash). */
+    apiBaseUrl: string;
+    /** OAuth issuer origin `boardwalk login` authenticates against (provider-agnostic). */
+    issuerUrl: string;
+    /** Public OAuth client id for the CLI's OAuth application. Null until configured. */
+    oauthClientId: string | null;
+    /** Fixed loopback port for the PKCE redirect (must be allowlisted on the OAuth application). */
+    loopbackPort: number;
+    /** Directory holding the credentials file (XDG config dir by default). */
+    configDir: string;
+}
+export declare function loadConfig(env?: NodeJS.ProcessEnv): CliConfig;
+export declare function trimTrailingSlash(url: string): string;

package/dist/config.js

@@ -0,0 +1,64 @@
+// CLI configuration — resolved from environment variables with sane defaults.
+//
+// Endpoints are NOT hardcoded into logic; they derive from env so the same binary targets prod
+// (the default), a dev stack, or a customer's SELF-HOSTED deployment on their own domain. The
+// identity provider behind `login` is an internal detail — the CLI only ever knows an "issuer URL",
+// never the vendor.
+import envPaths from "env-paths";
+/** Default API host. Self-hosters override with `BOARDWALK_API_DOMAIN=api.their-company.com`. */
+const DEFAULT_API_DOMAIN = "api.boardwalk.sh";
+/**
+ * Default OAuth issuer for `login`. Boardwalk self-hosts its OAuth server, so the issuer is the API
+ * host itself — the CLI fetches `<issuer>/.well-known/oauth-authorization-server` to discover the
+ * authorize page (web app) + token endpoint (api). Override with `BOARDWALK_ISSUER_URL` for dev.
+ */
+const DEFAULT_ISSUER_URL = `https://${DEFAULT_API_DOMAIN}`;
+/** The first-party CLI's public OAuth client id (registered in the backend's in-code client registry).
+ *  Shipped as a default so users don't configure it; override with `BOARDWALK_OAUTH_CLIENT_ID`. */
+const DEFAULT_OAUTH_CLIENT_ID = "boardwalk-cli";
+/** A fixed, memorable loopback port (cf. aws/gcloud). Must match the OAuth redirect allowlist. */
+const DEFAULT_LOOPBACK_PORT = 53682;
+export function loadConfig(env = process.env) {
+    const paths = envPaths("boardwalk", { suffix: "" });
+    return {
+        apiBaseUrl: resolveApiBaseUrl(env),
+        issuerUrl: trimTrailingSlash(env.BOARDWALK_ISSUER_URL ?? DEFAULT_ISSUER_URL),
+        oauthClientId: nonEmpty(env.BOARDWALK_OAUTH_CLIENT_ID) ?? DEFAULT_OAUTH_CLIENT_ID,
+        loopbackPort: parsePort(env.BOARDWALK_OAUTH_PORT) ?? DEFAULT_LOOPBACK_PORT,
+        configDir: nonEmpty(env.BOARDWALK_CONFIG_DIR) ?? paths.config,
+    };
+}
+/**
+ * API base URL, in precedence order:
+ *   1. `BOARDWALK_API_URL`    — a full URL (escape hatch for local http / non-standard ports)
+ *   2. `BOARDWALK_API_DOMAIN` — a hostname → `https://<domain>` (the self-host knob)
+ *   3. the default prod domain
+ */
+function resolveApiBaseUrl(env) {
+    const fullUrl = nonEmpty(env.BOARDWALK_API_URL);
+    if (fullUrl !== null)
+        return trimTrailingSlash(fullUrl);
+    const domain = nonEmpty(env.BOARDWALK_API_DOMAIN) ?? DEFAULT_API_DOMAIN;
+    return `https://${normalizeDomain(domain)}`;
+}
+/** Strip any scheme + trailing slashes from a domain so `https://<domain>` is well-formed. */
+function normalizeDomain(domain) {
+    return domain.replace(/^https?:\/\//, "").replace(/\/+$/, "");
+}
+export function trimTrailingSlash(url) {
+    return url.replace(/\/+$/, "");
+}
+function nonEmpty(value) {
+    if (value === undefined)
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+/** Parse a 1–65535 port from a string, or null when unset/invalid (caller falls back to default). */
+function parsePort(value) {
+    if (value === undefined)
+        return null;
+    const n = Number(value.trim());
+    return Number.isInteger(n) && n >= 1 && n <= 65535 ? n : null;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,EAAE;AACF,+FAA+F;AAC/F,8FAA8F;AAC9F,oGAAoG;AACpG,oBAAoB;AAEpB,OAAO,QAAQ,MAAM,WAAW,CAAC;AAejC,iGAAiG;AACjG,MAAM,kBAAkB,GAAG,kBAAkB,CAAC;AAC9C;;;;GAIG;AACH,MAAM,kBAAkB,GAAG,WAAW,kBAAkB,EAAE,CAAC;AAC3D;mGACmG;AACnG,MAAM,uBAAuB,GAAG,eAAe,CAAC;AAChD,kGAAkG;AAClG,MAAM,qBAAqB,GAAG,KAAK,CAAC;AAEpC,MAAM,UAAU,UAAU,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC7D,MAAM,KAAK,GAAG,QAAQ,CAAC,WAAW,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC;IACpD,OAAO;QACL,UAAU,EAAE,iBAAiB,CAAC,GAAG,CAAC;QAClC,SAAS,EAAE,iBAAiB,CAAC,GAAG,CAAC,oBAAoB,IAAI,kBAAkB,CAAC;QAC5E,aAAa,EAAE,QAAQ,CAAC,GAAG,CAAC,yBAAyB,CAAC,IAAI,uBAAuB;QACjF,YAAY,EAAE,SAAS,CAAC,GAAG,CAAC,oBAAoB,CAAC,IAAI,qBAAqB;QAC1E,SAAS,EAAE,QAAQ,CAAC,GAAG,CAAC,oBAAoB,CAAC,IAAI,KAAK,CAAC,MAAM;KAC9D,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,iBAAiB,CAAC,GAAsB;IAC/C,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAChD,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,iBAAiB,CAAC,OAAO,CAAC,CAAC;IACxD,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,oBAAoB,CAAC,IAAI,kBAAkB,CAAC;IACxE,OAAO,WAAW,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC;AAC9C,CAAC;AAED,8FAA8F;AAC9F,SAAS,eAAe,CAAC,MAAc;IACrC,OAAO,MAAM,CAAC,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AAChE,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,OAAO,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACjC,CAAC;AAED,SAAS,QAAQ,CAAC,KAAyB;IACzC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACrC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;AAC7C,CAAC;AAED,qGAAqG;AACrG,SAAS,SAAS,CAAC,KAAyB;IAC1C,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACrC,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IAC/B,OAAO,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAChE,CAAC"}

package/dist/credentials.d.ts

@@ -0,0 +1,23 @@
+/** A logged-in user's OAuth session. `null` fields = the IdP omitted them (e.g. no refresh token). */
+export interface StoredSession {
+    accessToken: string;
+    refreshToken: string | null;
+    /** Absolute access-token expiry, epoch ms; null = unknown (treated as non-expiring). */
+    expiresAt: number | null;
+    /** The OAuth client id used — needed to refresh. */
+    clientId: string | null;
+    /** The token endpoint to refresh against. */
+    tokenEndpoint: string | null;
+    scope: string | null;
+}
+export declare class CredentialStore {
+    private readonly filePath;
+    constructor(filePath: string);
+    static atConfigDir(configDir: string): CredentialStore;
+    getSession(): StoredSession | null;
+    putSession(session: StoredSession): void;
+    /** Remove any stored session (logout). Idempotent — a missing file is fine. */
+    clear(): void;
+    private read;
+    private write;
+}

package/dist/credentials.js

@@ -0,0 +1,69 @@
+// CredentialStore — the on-disk session written by `boardwalk login`, read by every authenticated
+// command.
+//
+// v0 storage: a single JSON file at `<configDir>/credentials.json`, dir mode 0700, file mode 0600
+// (owner-only) — the same posture as the `gh` / `aws` CLIs. AES-at-rest + an OS keychain are a
+// hardening follow-up; the interface here (get/put/clear a session) doesn't change when that lands.
+import { mkdirSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+export class CredentialStore {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    static atConfigDir(configDir) {
+        return new CredentialStore(join(configDir, "credentials.json"));
+    }
+    getSession() {
+        const session = this.read().session;
+        return session !== undefined && isValidSession(session) ? session : null;
+    }
+    putSession(session) {
+        this.write({ session });
+    }
+    /** Remove any stored session (logout). Idempotent — a missing file is fine. */
+    clear() {
+        try {
+            rmSync(this.filePath, { force: true });
+        }
+        catch {
+            // Best-effort: a missing/locked file shouldn't make logout fail.
+        }
+    }
+    read() {
+        let raw;
+        try {
+            raw = readFileSync(this.filePath, "utf8");
+        }
+        catch {
+            return {}; // missing/unreadable → no credentials
+        }
+        try {
+            const parsed = JSON.parse(raw);
+            if (typeof parsed === "object" && parsed !== null && "session" in parsed) {
+                const session = parsed.session;
+                if (isValidSession(session))
+                    return { session };
+            }
+        }
+        catch {
+            // Malformed file → treat as no credentials rather than crashing the command.
+        }
+        return {};
+    }
+    write(file) {
+        mkdirSync(dirOf(this.filePath), { recursive: true, mode: 0o700 });
+        writeFileSync(this.filePath, `${JSON.stringify(file, null, 2)}\n`, { mode: 0o600 });
+    }
+}
+function dirOf(filePath) {
+    const idx = filePath.lastIndexOf("/");
+    return idx <= 0 ? "." : filePath.slice(0, idx);
+}
+function isValidSession(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const s = value;
+    return typeof s.accessToken === "string" && s.accessToken.length > 0;
+}
+//# sourceMappingURL=credentials.js.map

package/dist/credentials.js.map

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

package/dist/deployment.d.ts

@@ -0,0 +1,44 @@
+import { type BuiltArtifact } from "./artifact.js";
+import type { BoardwalkClient, WorkflowSummary } from "./client.js";
+export interface PreparedProgram {
+    name: string;
+    /** Entry module inside the artifact (e.g. `index.mjs`). */
+    entry: string;
+    /** The built, content-addressed program artifact (tarball + digest + metadata). */
+    artifact: BuiltArtifact;
+}
+/**
+ * Resolve a target path to its deployable artifact: build the program (bundle + assets → tarball,
+ * content-addressed) and extract `meta.name` from the bundled entry for the deploy identity.
+ */
+export declare function loadProgram(file: string): Promise<PreparedProgram>;
+export interface DeployPlan {
+    action: "create" | "update";
+    name: string;
+    /** Present only for `update` — the existing workflow id to PUT. */
+    workflowId?: string;
+}
+/** Decide create vs update by matching the program name against the org's existing workflows. */
+export declare function planDeploy(existing: readonly WorkflowSummary[], name: string): DeployPlan;
+export interface DeployResultSummary {
+    workflowId: string;
+    orgSlug: string;
+    versionNumber: number;
+    /** "created" a new workflow, "updated" the linked one, or "adopted" an existing same-name one. */
+    outcome: "created" | "updated" | "adopted";
+    /** True when this deploy wrote a `.gitignore` entry for `.boardwalk/`. */
+    gitignoreUpdated: boolean;
+}
+export interface DeployContext {
+    /** Org slug from `--org`; falls back to the link's orgSlug. */
+    orgSlug?: string | undefined;
+    /** The original target path (used to locate the project dir for the link). */
+    target: string;
+    prog: PreparedProgram;
+}
+/**
+ * Deploy the program, honoring the project link: upload the artifact, then update the linked workflow
+ * by id (rename-safe); when unlinked, adopt an existing same-name workflow or create a new one. Always
+ * (re)writes the link so the next deploy/run is pinned.
+ */
+export declare function deployWithLink(client: BoardwalkClient, ctx: DeployContext): Promise<DeployResultSummary>;