@bevel-software/platform-core-backend 0.8.0 → 0.9.0

package/dist/modules/workspace/startup/kb-git.js

@@ -0,0 +1,86 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+/**
+ * The startup phase's own git plumbing — the runner owns every remote and
+ * repository operation of the phase (steps only declare buffered ops), so
+ * this is deliberately small and self-contained rather than borrowed from
+ * the runtime workspace service.
+ */
+/** Fallback committer identity; workflow commits override with `--author`. */
+export const BOT_NAME = 'Bevel Workflow';
+export const BOT_EMAIL = 'bevel-workflow@bevel.software';
+/**
+ * Scrub credentials from anything that reaches a log or an error message:
+ * the configured token wherever it appears, and URL userinfo — a remote
+ * spelled `https://user:pass@host` would otherwise leak `pass` verbatim
+ * through every git failure that quotes the URL back.
+ */
+export function redactSecret(text) {
+    const token = process.env.GITHUB_TOKEN;
+    const scrubbed = token ? text.replaceAll(token, '***') : text;
+    return scrubbed.replace(/:\/\/[^/@\s]+@/g, '://***@');
+}
+/**
+ * Per-invocation `-c` config. Long paths always (Windows checkouts of deep
+ * KB trees); when a token is present, an inline credential helper that reads
+ * it from the environment at call time — the secret never appears in argv.
+ */
+function credArgs(gitUsername) {
+    const args = ['-c', 'core.longpaths=true'];
+    if (process.env.GITHUB_TOKEN) {
+        args.push('-c', `credential.helper=!f() { echo "username=${gitUsername}"; echo "password=$GITHUB_TOKEN"; }; f`);
+    }
+    return args;
+}
+export async function git(cwd, gitUsername, args) {
+    try {
+        const { stdout } = await execFileAsync('git', [...credArgs(gitUsername), ...args], {
+            cwd,
+            // A stalled remote must FAIL the phase, not hang the boot forever —
+            // fail-closed (and KB_SAFE_BOOT's demotion) can only engage on an error
+            // that actually arrives. 10 minutes is generous for the largest clone.
+            timeout: 600_000,
+            // The 1MiB default truncates `ls-remote --heads` on remotes with very
+            // many branches, which would silently drop heads from the phase's view.
+            maxBuffer: 64 * 1024 * 1024,
+            // A credential prompt must fail the phase, not hang the boot forever
+            // waiting on a terminal nobody is watching.
+            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+        });
+        return stdout.toString();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(redactSecret(`git ${args[0]} failed: ${msg}`));
+    }
+}
+export async function stampIdentity(repo, gitUsername) {
+    await git(repo, gitUsername, ['config', 'user.name', BOT_NAME]);
+    await git(repo, gitUsername, ['config', 'user.email', BOT_EMAIL]);
+}
+/** Branch names present on the remote, from `ls-remote --heads`. */
+export async function lsRemoteHeads(repoUrl, gitUsername) {
+    const out = await git(os.tmpdir(), gitUsername, ['ls-remote', '--heads', repoUrl]);
+    const heads = new Set();
+    for (const line of out.split('\n')) {
+        const m = /\srefs\/heads\/(.+)$/.exec(line.trim());
+        if (m)
+            heads.add(m[1]);
+    }
+    return heads;
+}
+/** A temp dir that is always removed, success or failure. */
+export async function withTempDir(fn) {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'kb-startup-'));
+    try {
+        return await fn(dir);
+    }
+    finally {
+        await fs.rm(dir, { recursive: true, force: true }).catch(() => { });
+    }
+}
+//# sourceMappingURL=kb-git.js.map

package/dist/modules/workspace/startup/kb-git.js.map

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

package/dist/modules/workspace/startup/kb-startup-runner.d.ts

@@ -0,0 +1,74 @@
+import type { OnServerStart } from './on-server-start.js';
+/**
+ * The KB startup phase: run every registered {@link OnServerStart} step, in
+ * order, against lazily-cloned branch handles, then land one commit per
+ * dirty branch. Invoked at the deployment's two quiet moments — boot (before
+ * routes mount) and first-time setup completion (the app is gated shut until
+ * then) — and never again while the process serves.
+ *
+ * Fully fail-closed: any failure this phase cannot DECLARE (an unhandled
+ * step throw, an unreachable remote, a clone that will not come down, a
+ * refused write) throws out of `runAll` and stops the boot. The container's
+ * restart policy is the retry — each attempt at boot time on quiet trees —
+ * so an environmental failure converges without a human the moment the
+ * environment returns. The one carve-out: a push rejected because a
+ * concurrent replica won rolls back and continues; the winner already landed
+ * the same idempotent changes, and stopping the loser would make every
+ * multi-replica deploy flappy by design.
+ *
+ * `KB_SAFE_BOOT=1` is the break-glass demotion: on the first failure the
+ * phase resets every uncommitted tree, abandons the rest of the phase, and
+ * lets the server boot UNMAINTAINED so an admin can get in and rescue —
+ * loudly, at boot and in the log, because an env var outlives the emergency.
+ */
+export interface KbStartupRunnerOptions {
+    kbRepoUrl: () => string;
+    gitUsername: () => string;
+    workspacesRoot: string;
+    kbDirName: string;
+    templateDir: string;
+    defaultBranch: () => string;
+    protectedBranches: () => readonly string[];
+    /** Admins written into a freshly-seeded repo's roles.yaml (`ADMIN_EMAIL`). */
+    seedAdminEmails: readonly string[];
+    /** The ordered step chain — core's steps plus whatever the distribution appends. */
+    steps: readonly OnServerStart[];
+    /** The empty-remote seed commit builder (template tree + roles.yaml), injected
+        so the runner stays free of template knowledge. Receives the temp dir to
+        fill; the runner handles init/commit/push around it. Resolves to the
+        repo-relative paths the builder GENERATED itself (rather than copied from
+        the template) — the runner force-adds them after `git add -A`, so a
+        template `.gitignore` rule can never silently drop a required seed file
+        from the commit. */
+    buildSeedTree: (dir: string) => Promise<string[]>;
+}
+export declare class KbStartupRunner {
+    private readonly opts;
+    constructor(opts: KbStartupRunnerOptions);
+    /**
+     * Run the whole phase. Throws to stop the boot; returns normally when the
+     * KB is fully maintained (or safe boot abandoned the phase, loudly).
+     */
+    runAll(): Promise<void>;
+    /**
+     * Remote preparation — runner machinery, not a step, because every remote
+     * failure mode here is the runner's to own: an EMPTY remote gets the full
+     * seed commit pushed to every protected branch; missing protected refs are
+     * created from the best base. Returns the remote's head names (post-seed).
+     */
+    private ensureRemote;
+    private buildContext;
+    /**
+     * The branch's working copy at the runtime layout
+     * (`<workspacesRoot>/<id>/<kbDirName>`), so the workspace service finds it
+     * on disk afterwards. A surviving clone is fast-forwarded to origin when
+     * that is a pure fast-forward; a clone that is AHEAD (a crash before push
+     * left committed work) is left alone — maintenance lands on top and the
+     * push either carries both or rejects and rolls back, and the pending-
+     * commit recovery owns that work, not this phase.
+     */
+    private ensureClone;
+    /** One commit per dirty branch; push; the replica carve-out on rejection. */
+    private finalize;
+}
+//# sourceMappingURL=kb-startup-runner.d.ts.map

package/dist/modules/workspace/startup/kb-startup-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kb-startup-runner.d.ts","sourceRoot":"","sources":["../../../../src/modules/workspace/startup/kb-startup-runner.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAY,aAAa,EAAsB,MAAM,sBAAsB,CAAC;AAGxF;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,MAAM,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,MAAM,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,MAAM,CAAC;IAC5B,iBAAiB,EAAE,MAAM,SAAS,MAAM,EAAE,CAAC;IAC3C,8EAA8E;IAC9E,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,oFAAoF;IACpF,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IAChC;;;;;;2BAMuB;IACvB,aAAa,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CACnD;AAED,qBAAa,eAAe;IACd,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,sBAAsB;IAEzD;;;OAGG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IA+G7B;;;;;OAKG;YACW,YAAY;IAyE1B,OAAO,CAAC,YAAY;IAkBpB;;;;;;;;OAQG;YACW,WAAW;IA0BzB,6EAA6E;YAC/D,QAAQ;CAoFvB"}