@owlmeans/viable-sdk 0.1.18-rc.1

package/build/executor/shell.js

@@ -0,0 +1,280 @@
+import fs from 'fs-extra';
+import { randomUUID } from 'node:crypto';
+import p from 'node:path';
+import { formatIntegrityReport, TARGET_BOOTCHECK_MARKER, TARGET_BOOTCHECK_PORT, TARGET_BOOTCHECK_SCHEMA } from '@owlmeans/viable-common';
+import { probePort, readEnvFile, ROOT_ENV_FILE, serviceEndpoint } from '../project/env.js';
+import { restartApi } from '../run/state.js';
+import { createBootCheckJob, runBootCheck } from './boot-check.js';
+import { backendEnv, frontendEnv } from './env.js';
+import { verifyTarget } from './integrity.js';
+import { apiPath, hasWorker, libraryPaths, webPath, workerPath } from './layout.js';
+import { runCommand, runScript } from './spawn.js';
+/**
+ * The shell half of the local executor — every `SlotShellCommand`, against a directory.
+ *
+ * The contract every method answers with is the publisher's: **error text, or `null` for
+ * success**. It is not a transcript — a command that fails returns the diagnostics a fixer or a
+ * person can act on, and a command that succeeds returns nothing at all.
+ */
+/**
+ * The one reason a script refuses that is NOT a verdict about the code.
+ *
+ * A build with nothing to build on is an ordinary no-op that the next trigger repeats correctly —
+ * it happens between attaching to a fresh clone and the first install. It must not be reported as
+ * a failed build, or the connector announces broken code during a window in which nothing was
+ * even attempted.
+ */
+export const NOT_INSTALLED_REASON = "cannot run: the target's dependencies are not installed yet";
+/** Whether a refusal describes the code, or merely a window in which nothing ran. */
+export const isBuildVerdict = (reason) => reason == null || !reason.includes(NOT_INSTALLED_REASON);
+/**
+ * One boot-check job per directory.
+ *
+ * Module-level rather than per-helper because a helper is built per command: two `BootCheck`
+ * calls would otherwise each start an instance onto the same port, and a `BootCheckStatus` would
+ * read a job nobody had started.
+ */
+const _jobs = new Map();
+const jobFor = (dir) => {
+    const existing = _jobs.get(dir);
+    if (existing != null)
+        return existing;
+    const job = createBootCheckJob();
+    _jobs.set(dir, job);
+    return job;
+};
+export const createLocalShellHelper = (fileHelper, subproject) => {
+    const root = p.resolve(fileHelper.getRootPath());
+    /**
+     * Refuse to run anything in a tree that is no longer the generated application.
+     *
+     * Every command below executes something the tree decides: `bun install` runs the lifecycle
+     * hooks a `package.json` declares, and `bun run build` runs its `scripts.build`. Both are as
+     * writable as any source file — by the editor, by the agent, and by a git merge — so the guard
+     * belongs in front of the spawn, not in front of whichever caller was considered.
+     *
+     * Returned as text rather than thrown, because that is the contract every method here already
+     * answers with. A caller needs no new branch to notice.
+     */
+    const refusal = async (prefix = 'Refused') => {
+        const report = await verifyTarget(root);
+        return report.ok
+            ? null
+            : `${prefix}: the project in this directory is not a Viable application\n`
+                + formatIntegrityReport(report);
+    };
+    /**
+     * Everything that must be true before a script may be spawned, in order.
+     *
+     * Each check exists because the failure it replaces lies about the cause. A missing cwd is
+     * reported by `posix_spawn` as `ENOENT … '/bin/sh'`, which sends every reader after a broken
+     * toolchain while the real fault is an initialization that never happened. A missing
+     * `node_modules/.bin` makes every `scripts.build` exit 127 with `script "build" exited with
+     * code 127`, which names the script rather than the reason and reads as a broken template.
+     */
+    const runTargetScript = async (script, cwd, env) => {
+        if (!await fs.pathExists(cwd)) {
+            return `${script} cannot run: ${cwd} does not exist `
+                + `— the target project was never initialized in this directory`;
+        }
+        if (!await fs.pathExists(p.resolve(root, 'node_modules', '.bin'))) {
+            return `${script} ${NOT_INSTALLED_REASON}`;
+        }
+        const refused = await refusal(`${script} refused`);
+        if (refused != null)
+            return refused;
+        return await runScript(script, cwd, env);
+    };
+    /**
+     * Build every package this tree consumes through its `build/` output, in dependency order.
+     *
+     * Not a hard-coded `common`. v2 splits the shared code in two — `common` and the `backend`
+     * library `api` and `worker` compile against — so a type check that built only `common` ran
+     * against a stale or absent `sources/backend/build` and reported errors about the package it
+     * had just failed to build. `tsc -b` is incremental, so re-running this costs a tsbuildinfo
+     * read once the output is current.
+     */
+    const buildLibraries = async () => {
+        for (const cwd of libraryPaths(root)) {
+            const error = await runTargetScript('build', cwd);
+            if (error != null) {
+                return error;
+            }
+        }
+        return null;
+    };
+    const buildWorker = async () => {
+        const dir = workerPath(root);
+        if (dir == null || !hasWorker(root)) {
+            return null;
+        }
+        return await runTargetScript('build', dir);
+    };
+    const helper = {
+        bun: async (args, options) => {
+            const refused = await refusal();
+            if (refused != null)
+                return refused;
+            const cmd = `bun ${args ?? 'install'}`;
+            return await runCommand(cmd, { cwd: fileHelper.getRootPath(options?.subproject ?? subproject) });
+        },
+        /**
+         * Throw the lockfile away and install again.
+         *
+         * The truncate is the point. `bun install` on its own reproduces whatever the lockfile says,
+         * and a target's lockfile was written the day the project was created — so a framework
+         * package republished afterwards is invisible to it no matter how often the target is
+         * rebuilt. Emptied rather than deleted, matching initialization: bun reads an empty file as
+         * "no lockfile", so a failed install leaves a state the next attempt resolves cleanly instead
+         * of one where a stale lock has come back.
+         */
+        reinstall: async () => {
+            const refused = await refusal();
+            if (refused != null)
+                return refused;
+            try {
+                await fs.writeFile(p.join(root, 'bun.lock'), '');
+            }
+            catch {
+                // No lockfile to clear is not a failure — a tree may predate one, or have had it removed.
+            }
+            return await runCommand('bun install', { cwd: root });
+        },
+        buildCommon: async () => {
+            const refused = await refusal();
+            if (refused != null)
+                return refused;
+            return await buildLibraries();
+        },
+        validate: async (subprojectOverride) => {
+            const refused = await refusal();
+            if (refused != null)
+                return refused;
+            const libraries = await buildLibraries();
+            if (libraries != null) {
+                return libraries;
+            }
+            // The diagnostics are on stdout; `tsc`'s stderr is about the compiler, not about the code.
+            return await runCommand('bunx tsc --noEmit', {
+                cwd: fileHelper.getRootPath(subprojectOverride ?? subproject),
+                stdoutOnly: true,
+            });
+        },
+        /** The buildability check for the UI: the browser bundle really built, or the reason it did not. */
+        validateWithRenderer: async () => await buildLibraries() ?? await runTargetScript('build', webPath(root), await frontendEnv(root)),
+        /**
+         * Rebuild the whole target, in dependency order.
+         *
+         * The libraries first, because everything else resolves them from `node_modules` at RUN time
+         * and follows each to its `build/index.js` — a bundle built before them starts with
+         * `Cannot find package '<slug>-backend'`, a message about a dependency for a build that never
+         * happened. The remaining three are independent, so all of them run and their problems are
+         * reported together rather than one round trip at a time.
+         */
+        build: async () => {
+            const libraries = await buildLibraries();
+            if (libraries != null) {
+                return libraries;
+            }
+            const errors = [
+                await runTargetScript('build', apiPath(root)),
+                await buildWorker(),
+                await runTargetScript('build', webPath(root), await frontendEnv(root)),
+            ].filter((error) => error != null);
+            return errors.length > 0 ? errors.join('\n') : null;
+        },
+        /** Build the api only — the type check the frontend renderer build cannot give it. */
+        validateBackend: async () => await buildLibraries() ?? await runTargetScript('build', apiPath(root)),
+        /**
+         * Reconcile the target's database with its code.
+         *
+         * The target owns its own structure: every `@owlmeans/postgres` resource creates and updates
+         * its table while the context initializes. So a sync is not a command run against the source
+         * tree — it is *check that the database is there, then restart the backend* — and there is
+         * nothing to generate and no migration file to apply.
+         *
+         * A local target's database is the developer's. The platform provisions none, so an absent
+         * URL is reported by NAME rather than repaired: it is a line the person has to write, and
+         * "database unavailable" would send them looking at a server instead.
+         */
+        dbSync: async () => {
+            const values = await readEnvFile(root, ROOT_ENV_FILE);
+            const url = values.DATABASE_URL ?? '';
+            if (url === '') {
+                return `DATABASE_URL is not set in ${ROOT_ENV_FILE}. A local target uses a database on `
+                    + `this machine and the platform provisions none — set it and run this again.`;
+            }
+            const endpoint = serviceEndpoint(url);
+            if (endpoint == null) {
+                return `DATABASE_URL in ${ROOT_ENV_FILE} is not a URL naming a host and a port.`;
+            }
+            if (!await probePort(endpoint.host, endpoint.port)) {
+                return `Nothing is listening at ${endpoint.host}:${endpoint.port} — `
+                    + `the database DATABASE_URL names is not reachable from this machine.`;
+            }
+            return await restartApi(root);
+        },
+        /**
+         * Answering, not enforcing.
+         *
+         * The connector refuses on its own before every spawn regardless; this exists so a caller can
+         * ask BEFORE letting a merge reach a build, and report the violations to the person whose
+         * repository they belong to.
+         */
+        integrity: async () => {
+            const report = await verifyTarget(root);
+            return {
+                result: report.ok ? null : formatIntegrityReport(report),
+                ok: report.ok,
+                violations: report.violations.map(violation => `${violation.path}: ${violation.detail}`),
+            };
+        },
+        /**
+         * Start a real boot in isolation and return at once.
+         *
+         * A second start joins the running check rather than spawning another instance onto the port.
+         * The verdict is read with {@link bootCheckStatus}; `wait` is the legacy blocking path for a
+         * caller that predates the job.
+         */
+        bootCheck: async (options = {}) => {
+            const job = jobFor(root);
+            job.start(async () => {
+                // `skipBuild` reaches `dist/index.js` with no build in front of it, so the guard has to be
+                // here and not only inside the build.
+                const refused = await refusal('Boot check refused');
+                if (refused != null) {
+                    return { ok: false, phase: 'build', error: refused };
+                }
+                const values = await readEnvFile(root, ROOT_ENV_FILE);
+                if ((values.DATABASE_URL ?? '') === '') {
+                    // Without a database the check cannot connect, and reporting that as a boot failure
+                    // would blame the generated code for a target that was never configured.
+                    return {
+                        ok: false, phase: 'schema',
+                        error: `Boot check skipped: ${ROOT_ENV_FILE} declares no DATABASE_URL`,
+                    };
+                }
+                return await runBootCheck({
+                    port: TARGET_BOOTCHECK_PORT,
+                    marker: TARGET_BOOTCHECK_MARKER,
+                    cwd: apiPath(root),
+                    env: {
+                        ...await backendEnv(root),
+                        BACKEND_PORT: `${TARGET_BOOTCHECK_PORT}`,
+                        DATABASE_SCHEMA: TARGET_BOOTCHECK_SCHEMA,
+                    },
+                    bootId: randomUUID(),
+                    ...(options.skipBuild === true
+                        ? {}
+                        : { build: async () => await buildLibraries() ?? await runTargetScript('build', apiPath(root)) }),
+                });
+            });
+            if (options.wait !== true)
+                return null;
+            return await job.pending() ?? job.status().report;
+        },
+        bootCheckStatus: async () => jobFor(root).status(),
+    };
+    return helper;
+};
+//# sourceMappingURL=shell.js.map

package/build/executor/shell.js.map

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

package/build/executor/spawn.d.ts

@@ -0,0 +1,111 @@
+import type { ChildProcess } from 'node:child_process';
+/**
+ * Everything that starts, bounds or ends a child process on the developer's machine.
+ *
+ * Shared by the shell commands, the boot check and the local run so the three cannot disagree
+ * about what a failure looks like or when a port is free — the publisher learned both lessons the
+ * expensive way, and neither of them is about Kubernetes.
+ */
+/**
+ * Output ceiling for every validate/build child process.
+ *
+ * Node's default is 1 MiB, and a target project with a few hundred type errors exceeds it: the
+ * child is killed and the fixer receives `stdout maxBuffer length exceeded` instead of the errors
+ * it is supposed to repair.
+ */
+export declare const MAX_OUTPUT_BUFFER: number;
+/** One-shot script ceiling. A build that outlives it is wedged, not slow. */
+export declare const BUILD_TIMEOUT = 300000;
+/**
+ * Compose a failed command's output into the text a fixer reads.
+ *
+ * Never interpolate the `ExecException` beside `stderr`: its string form is
+ * `Error: Command failed: <cmd>\n<stderr>`, so the naive `${stdout} ${error} ${stderr}` shape
+ * emitted every diagnostic twice and prefixed a runner sentence that is not a diagnostic at all.
+ * Both survive into the fix conversation — the duplicate doubles the prompt for nothing, and the
+ * preamble is what a model latches onto when it cannot see a real cause. Say it once, and say
+ * what actually ran only when there is nothing else to report.
+ */
+export declare const failureOutput: (error: unknown, stdout: string, stderr: string, cmd: string) => string;
+export interface RunOptions {
+    cwd: string;
+    env?: Record<string, string>;
+    /** Answer with stdout alone on failure — what a type check's diagnostics are. */
+    stdoutOnly?: boolean;
+}
+/**
+ * Run a shell command and answer "error text, or null".
+ *
+ * The one contract every shell command here shares. A caller never has to know whether the child
+ * exited non-zero, failed to spawn or produced nothing — those are all one answer.
+ */
+export declare const runCommand: (cmd: string, options: RunOptions) => Promise<string | null>;
+/**
+ * Run one of the target's own `scripts.*`, bounded.
+ *
+ * `spawn` rather than `exec` because a build's output is unbounded and streaming it costs nothing,
+ * and because a wedged `bunx` resolving forever must die rather than hold the caller open. The
+ * timeout is reported as a verdict, not thrown, so it reaches the same channel a failed build does.
+ */
+export declare const runScript: (script: string, cwd: string, env?: Record<string, string>) => Promise<string | null>;
+/**
+ * Bound one whole dispatch, whatever it is.
+ *
+ * Every operation below already bounds itself, but one that wedges AROUND its own bound — a lock
+ * nothing releases, a promise that never settles — holds the caller open with nothing to report,
+ * and the caller's timeout becomes the only limit. Reaching this means the operation failed to
+ * bound itself, not that it needed longer.
+ */
+export declare const withDeadline: <T>(label: string, ms: number, fn: () => Promise<T>) => Promise<T>;
+/** Whether anything answers a TCP connect on a local port. */
+export declare const probeListening: (port: number, timeoutMs?: number) => Promise<boolean>;
+/**
+ * Wait until nothing answers on a local port.
+ *
+ * The child spawned here is a shell wrapping `bun`, so the shell's exit is not proof the target is
+ * gone: a signal the shell dies from and `bun` survives leaves an orphan that still owns the port.
+ * Whether the port answers is the only fact that decides whether a replacement can bind, so a
+ * restart waits on that and never on an exit event.
+ */
+export declare const waitForPortFree: (port: number, timeoutMs?: number, pollMs?: number) => Promise<boolean>;
+/**
+ * Terminate a detached child's whole process group and wait until it is actually gone.
+ *
+ * Awaiting matters: the caller restarts right after, and a process still holding the port makes
+ * the replacement lose the bind and exit — leaving nothing listening and no error anyone reads.
+ */
+export declare const killGroupAndWait: (proc: ChildProcess, options?: {
+    term?: number;
+    kill?: number;
+}) => Promise<void>;
+/**
+ * Take a port back from a leftover running the same command.
+ *
+ * A connector that was killed — a host restart, a Ctrl-C, a crashed run — leaves its DETACHED
+ * children alive, because detaching them is what keeps a build from dying with the tool that
+ * started it. What survives holds the target's port, and every later attempt then fails with the
+ * target's own "the api port is already in use", which reads as a defect in the generated app.
+ *
+ * Matched by the marker the spawn carries, never by the port alone: a process this connector did
+ * not start is not ours to signal, whatever it is sitting on.
+ */
+export declare const reclaimPort: (port: number, marker: string) => Promise<boolean>;
+/**
+ * The pids whose command line carries a marker.
+ *
+ * `/proc` rather than `ps`, for the same reason the publisher reads it: no shell, no parsing of a
+ * format that differs per platform. Somewhere without `/proc` simply has nothing to reclaim, which
+ * is the honest answer there.
+ */
+export declare const findProcesses: (needles: string | string[]) => Promise<number[]>;
+/**
+ * Signal a process GROUP, falling back to the process.
+ *
+ * The negative pid is the point: a child spawned detached through a shell survives a signal aimed
+ * at the shell's own pid, and what survives is the `bun` process holding the port.
+ */
+export declare const signalGroup: (pid: number | undefined, signal: NodeJS.Signals) => boolean;
+/** Whether a recorded pid is still a live process. */
+export declare const isAlive: (pid: number | undefined) => boolean;
+export declare const delay: (ms: number) => Promise<void>;
+//# sourceMappingURL=spawn.d.ts.map

package/build/executor/spawn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn.d.ts","sourceRoot":"","sources":["../../src/executor/spawn.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAItD;;;;;;GAMG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,QAAmB,CAAA;AAEjD,6EAA6E;AAC7E,eAAO,MAAM,aAAa,SAAU,CAAA;AASpC;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,UACjB,OAAO,UAAU,MAAM,UAAU,MAAM,OAAO,MAAM,KAC1D,MAKF,CAAA;AAED,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5B,iFAAiF;IACjF,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAED;;;;;GAKG;AACH,eAAO,MAAM,UAAU,QAAe,MAAM,WAAW,UAAU,KAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAkBrF,CAAA;AAEJ;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,WACZ,MAAM,OAAO,MAAM,QAAQ,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KACxD,OAAO,CAAC,MAAM,GAAG,IAAI,CA4BtB,CAAA;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,GAAU,CAAC,SAC3B,MAAM,MAAM,MAAM,MAAM,MAAM,OAAO,CAAC,CAAC,CAAC,KAC9C,OAAO,CAAC,CAAC,CAeX,CAAA;AAED,8DAA8D;AAC9D,eAAO,MAAM,cAAc,SAAgB,MAAM,yBAAsB,OAAO,CAAC,OAAO,CAYlF,CAAA;AAEJ;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,SACpB,MAAM,0CACX,OAAO,CAAC,OAAO,CAWjB,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,SACrB,YAAY,YAAW;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,KAC5D,OAAO,CAAC,IAAI,CAcd,CAAA;AAuCD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW,SAAgB,MAAM,UAAU,MAAM,KAAG,OAAO,CAAC,OAAO,CAiB/E,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,YAAmB,MAAM,GAAG,MAAM,EAAE,KAAG,OAAO,CAAC,MAAM,EAAE,CAsBhF,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,QAAS,MAAM,GAAG,SAAS,UAAU,MAAM,CAAC,OAAO,KAAG,OAe7E,CAAA;AAED,sDAAsD;AACtD,eAAO,MAAM,OAAO,QAAS,MAAM,GAAG,SAAS,KAAG,OASjD,CAAA;AAED,eAAO,MAAM,KAAK,OAAc,MAAM,KAAG,OAAO,CAAC,IAAI,CAGnD,CAAA"}