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

package/dist/modules/workspace/startup/on-server-start.d.ts

@@ -0,0 +1,105 @@
+/**
+ * The KB startup contract: every migration and scaffolding concern runs here,
+ * at the deployment's quiet moments, and nowhere else.
+ *
+ * There are exactly two occasions, both provably quiet (no user holds a lock,
+ * no edit is mid-flight): SERVER BOOT, before routes mount; and FIRST-TIME
+ * SETUP COMPLETION, when the branch model is configured through the setup
+ * screen — the app is gated shut until exactly that moment. Any later re-run
+ * would race live sessions on the very working clones it maintains, which is
+ * why there is no retry tick, no lazy per-branch trigger, and no maintenance
+ * on runtime branch opens, ever. A failed boot is retried by the container's
+ * restart policy — each attempt at boot time, on quiet trees.
+ *
+ * Failure model, fully fail-closed: the server either completes the phase or
+ * does not serve. An UNHANDLED throw from a step stops the boot — the same
+ * contract a DB migration has. A failure the author knows is survivable must
+ * be DECLARED via the result. `KB_SAFE_BOOT=1` is the break-glass demotion
+ * (see the runner).
+ */
+export interface OnServerStart {
+    /** Shown in logs and error messages: "groups-to-plugins", "template-files", … */
+    readonly name: string;
+    run(ctx: ServerStartContext): Promise<StepResult>;
+}
+/**
+ * What the runner should do next. Every declared outcome asserts "the tree is
+ * in a state later steps can safely run against".
+ */
+export type StepResult = 
+/** Fully done; declared ops apply. "Nothing to do" is `ok` with no ops. */
+{
+    outcome: 'ok';
+}
+/**
+ * Incomplete but VALID: declared ops still apply; the remainder is named
+ * and logged. The migration's refused conversions are exactly this.
+ */
+ | {
+    outcome: 'partial';
+    reason: string;
+}
+/**
+ * Did not complete: declared ops are discarded UNAPPLIED — the tree is
+ * untouched by construction, not by revert — and later steps continue.
+ */
+ | {
+    outcome: 'skipped';
+    reason: string;
+}
+/** Serving would be worse than being down. The deliberate kill switch. */
+ | {
+    outcome: 'stopBoot';
+    message: string;
+};
+export interface ServerStartContext {
+    /** The resolved template directory this build ships. */
+    readonly templateDir: string;
+    /** Handles are lazy — the clone happens on first `repoDir()`. */
+    defaultBranch(): Promise<KbBranch>;
+    protectedBranches(): Promise<KbBranch[]>;
+    /**
+     * Every branch on the remote, drafts included — and WRITABLE like any
+     * other: with maintenance applied uniformly at the quiet moment, migrating
+     * a draft alongside its target is what keeps its change-request diff down
+     * to the user's own changes. (The lazy era's read-only rule guarded
+     * against ASYMMETRIC application; uniform application inverts it — a
+     * stale draft against a migrated target diffs by the whole rename.)
+     */
+    allBranches(): Promise<KbBranch[]>;
+}
+/**
+ * One branch's working copy, with buffered writes. Steps never touch the
+ * disk: they READ via `repoDir()` and DECLARE operations, which the runner —
+ * the only writer — applies when the step returns `ok`/`partial` (so the next
+ * step sees the real, updated tree) and discards on `skipped`. The applier
+ * enforces the write layer's containment contract once — repo-relative
+ * paths, no escapes, no symlinks — instead of every step getting raw fs
+ * right.
+ */
+export interface KbBranch {
+    readonly name: string;
+    readonly isProtected: boolean;
+    /**
+     * Absolute path of the checked-out clone; clone-if-absent happens here.
+     * This is the READ seam: writing through the returned path is a contract
+     * violation by the step — steps are first-party trusted code, and the
+     * buffered-ops contract is a convention the runner enforces structurally,
+     * not a sandbox it defends.
+     */
+    repoDir(): Promise<string>;
+    /** Declare a file's full content at a repo-relative path. */
+    write(path: string, content: string | Uint8Array): void;
+    /** Declare a relocation — file or whole directory (the Groups→Plugins rename is one op). */
+    move(from: string, to: string): void;
+    /** Declare a file's removal. */
+    remove(path: string): void;
+    /**
+     * One honest line per logical change — the branch's commit message is built
+     * from these. Notes ride WITH the step's ops: kept when the step's outcome
+     * applies them (`ok`/`partial`), discarded together with them on `skipped` —
+     * a skipped step must not caption a commit made of other steps' changes.
+     */
+    note(line: string): void;
+}
+//# sourceMappingURL=on-server-start.d.ts.map

package/dist/modules/workspace/startup/on-server-start.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"on-server-start.d.ts","sourceRoot":"","sources":["../../../../src/modules/workspace/startup/on-server-start.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,aAAa;IAC5B,iFAAiF;IACjF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACnD;AAED;;;GAGG;AACH,MAAM,MAAM,UAAU;AACpB,2EAA2E;AACzE;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE;AACnB;;;GAGG;GACD;IAAE,OAAO,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACxC;;;GAGG;GACD;IAAE,OAAO,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACxC,0EAA0E;GACxE;IAAE,OAAO,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7C,MAAM,WAAW,kBAAkB;IACjC,wDAAwD;IACxD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,iEAAiE;IACjE,aAAa,IAAI,OAAO,CAAC,QAAQ,CAAC,CAAC;IACnC,iBAAiB,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IACzC;;;;;;;OAOG;IACH,WAAW,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;CACpC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B;;;;;;OAMG;IACH,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAC3B,6DAA6D;IAC7D,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAAC;IACxD,4FAA4F;IAC5F,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,gCAAgC;IAChC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B"}

package/dist/modules/workspace/startup/on-server-start.js

@@ -0,0 +1,21 @@
+/**
+ * The KB startup contract: every migration and scaffolding concern runs here,
+ * at the deployment's quiet moments, and nowhere else.
+ *
+ * There are exactly two occasions, both provably quiet (no user holds a lock,
+ * no edit is mid-flight): SERVER BOOT, before routes mount; and FIRST-TIME
+ * SETUP COMPLETION, when the branch model is configured through the setup
+ * screen — the app is gated shut until exactly that moment. Any later re-run
+ * would race live sessions on the very working clones it maintains, which is
+ * why there is no retry tick, no lazy per-branch trigger, and no maintenance
+ * on runtime branch opens, ever. A failed boot is retried by the container's
+ * restart policy — each attempt at boot time, on quiet trees.
+ *
+ * Failure model, fully fail-closed: the server either completes the phase or
+ * does not serve. An UNHANDLED throw from a step stops the boot — the same
+ * contract a DB migration has. A failure the author knows is survivable must
+ * be DECLARED via the result. `KB_SAFE_BOOT=1` is the break-glass demotion
+ * (see the runner).
+ */
+export {};
+//# sourceMappingURL=on-server-start.js.map

package/dist/modules/workspace/startup/on-server-start.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"on-server-start.js","sourceRoot":"","sources":["../../../../src/modules/workspace/startup/on-server-start.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG"}

package/dist/modules/workspace/startup/steps/groups-to-plugins.step.d.ts

@@ -0,0 +1,46 @@
+import type { OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';
+/**
+ * One-way migration of a knowledge base from `Groups/` to the Agent Plugins
+ * layout under `Plugins/` (https://agent-plugins.org, v1.0.0), as an
+ * {@link OnServerStart} step. (It began life as an in-place module run from
+ * the lazy top-up; that path is gone, and this is the only form.) Steps
+ * never write: every change is DECLARED on the branch handle
+ * (`move`/`write`/`remove`) and the runner applies it, while every read goes
+ * against the real, pre-step tree via `repoDir()`.
+ *
+ * Idempotent: a KB already on the new layout is untouched, and a half-finished
+ * run is completed by the next one.
+ *
+ * What moves — and what CONVERTS:
+ *
+ *   Groups/GTM/access.md            → Plugins/GTM/access.md            (stays put)
+ *   Groups/GTM/deploy/SKILL.md      → Plugins/GTM/skills/deploy/SKILL.md
+ *   Groups/GTM/web-search.tool      → Plugins/GTM/software.bevel.hexis/tools/web-search.tool
+ *   Groups/GTM/notion.tool (mcp)    → an entry in Plugins/GTM/mcp.json, and the
+ *                                     `.tool` file is DELETED — mcp.json is
+ *                                     authoritative for MCP servers now.
+ *                                     Plugins/GTM/plugin.json           (written)
+ *
+ * The mcp.json entry is keyed by the `.tool`'s manual id: that id is the
+ * namespace vault secrets bind to (`<id>_<VAR>`), so keeping it is what keeps
+ * every configured secret and completed OAuth grant bound. What mcp.json
+ * cannot carry — auth headers with `${VAR}` references, variable declarations,
+ * the local-only flag — moves into `plugin.json`'s
+ * `extensions["software.bevel.hexis"].mcpServers[<id>]` block, the reverse-DNS
+ * namespace the spec reserves for client-specific data. `http`/`inline`
+ * manuals still MOVE as `.tool` files: nothing but this platform can run them.
+ *
+ * Scope: EVERY branch, drafts included and writable (`ctx.allBranches()`) —
+ * maintenance applied uniformly at the quiet moment is what keeps a draft's
+ * change-request diff down to the user's own changes; a stale draft against a
+ * migrated target would diff by the whole rename.
+ *
+ * Outcomes: a per-manual NOT-converted refusal makes the step `partial` with
+ * the reasons (the declared ops for everything else still apply); a branch
+ * carrying BOTH roots contributes nothing but a note; everything else is `ok`.
+ */
+export declare class GroupsToPluginsStep implements OnServerStart {
+    readonly name = "groups-to-plugins";
+    run(ctx: ServerStartContext): Promise<StepResult>;
+}
+//# sourceMappingURL=groups-to-plugins.step.d.ts.map

package/dist/modules/workspace/startup/steps/groups-to-plugins.step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"groups-to-plugins.step.d.ts","sourceRoot":"","sources":["../../../../../src/modules/workspace/startup/steps/groups-to-plugins.step.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAY,aAAa,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAErG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,qBAAa,mBAAoB,YAAW,aAAa;IACvD,QAAQ,CAAC,IAAI,uBAAuB;IAE9B,GAAG,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,UAAU,CAAC;CAOxD"}